peaks-loop 3.0.0

package/dist/src/services/standards/project-standards-service.js

@@ -0,0 +1,574 @@
+import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, realpathSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir as osHomedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { buildToolLabel, componentLibraryLabel, cssFrameworkLabel, detectProjectContext } from './project-context.js';
+export class ProjectStandardsWriteTargetError extends Error {
+    code = 'PROJECT_STANDARDS_WRITE_TARGET_OUTSIDE_ROOT';
+    filePath;
+    projectRoot;
+    reason;
+    constructor(input) {
+        super(`Project standards write target '${input.filePath}' is rejected (reason: ${input.reason}); ` +
+            `writes must stay inside project root '${input.projectRoot}'. ` +
+            `Refusing to pollute the user-level ~/.claude/ baseline.`);
+        this.name = 'ProjectStandardsWriteTargetError';
+        this.filePath = input.filePath;
+        this.projectRoot = input.projectRoot;
+        this.reason = input.reason;
+    }
+}
+const SOURCE = {
+    sourceId: 'everything-claude-code',
+    url: 'https://github.com/affaan-m/everything-claude-code',
+    usage: 'curated-baseline-reference'
+};
+const SKILL_PREFLIGHT = {
+    appliesTo: ['peaks-rd', 'peaks-qa', 'peaks-solo'],
+    summary: 'peaks-rd、peaks-qa、peaks-solo 进入代码仓工作流时自动 preflight 项目规范。'
+};
+const SUPPORTED_LANGUAGES = new Set(['generic', 'typescript', 'javascript', 'python', 'go', 'rust']);
+function normalizeRoot(path) {
+    return realpathSync(resolve(path));
+}
+function isInsidePath(childPath, parentPath) {
+    const rel = relative(parentPath, childPath);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+function assertDirectoryNotSymlink(path) {
+    if (existsSync(path) && lstatSync(path).isSymbolicLink()) {
+        throw new Error('Project standards directory must stay inside the project root');
+    }
+}
+function assertRealPathInsideProject(path, projectRoot) {
+    if (!isInsidePath(realpathSync(path), projectRoot)) {
+        throw new Error('Project standards write target must stay inside the project root');
+    }
+}
+function assertWritablePathInsideProject(path, projectRoot) {
+    let currentPath = path;
+    while (!existsSync(currentPath)) {
+        currentPath = dirname(currentPath);
+    }
+    assertRealPathInsideProject(currentPath, projectRoot);
+}
+function assertSafeClaudeMdPath(filePath, projectRoot) {
+    if (!existsSync(filePath))
+        return;
+    if (lstatSync(filePath).isSymbolicLink() || !isInsidePath(realpathSync(filePath), projectRoot)) {
+        throw new Error('Project standards CLAUDE.md must stay inside the project root');
+    }
+}
+function assertSafeStandardsRoot(projectRoot) {
+    const resolvedRoot = normalizeRoot(projectRoot);
+    const claudeDir = join(resolvedRoot, '.claude');
+    const rulesDir = join(claudeDir, 'rules');
+    assertDirectoryNotSymlink(claudeDir);
+    assertDirectoryNotSymlink(rulesDir);
+    if (existsSync(rulesDir)) {
+        assertRealPathInsideProject(rulesDir, resolvedRoot);
+        return realpathSync(rulesDir);
+    }
+    return rulesDir;
+}
+function parseLanguage(value) {
+    const normalized = value.trim().toLowerCase();
+    if (SUPPORTED_LANGUAGES.has(normalized)) {
+        return normalized;
+    }
+    throw new Error('Unsupported standards language');
+}
+function detectLanguageInternal(projectRoot) {
+    if (existsSync(join(projectRoot, 'tsconfig.json')))
+        return 'typescript';
+    if (existsSync(join(projectRoot, 'package.json')))
+        return 'javascript';
+    if (existsSync(join(projectRoot, 'pyproject.toml')) || existsSync(join(projectRoot, 'requirements.txt')))
+        return 'python';
+    if (existsSync(join(projectRoot, 'go.mod')))
+        return 'go';
+    if (existsSync(join(projectRoot, 'Cargo.toml')))
+        return 'rust';
+    return 'generic';
+}
+/**
+ * Public alias for `detectLanguageInternal` so callers outside this
+ * module (e.g. `workspace-service.ts` for the slice 2026-06-16 RD#7
+ * auto-detect path) can ask the same heuristic without re-implementing
+ * the file-probe logic.
+ */
+export function detectLanguage(projectRoot) {
+    return detectLanguageInternal(projectRoot);
+}
+function renderHeader(title) {
+    return [
+        `# ${title}`,
+        '',
+        'Source: Peaks curated baseline; everything-claude-code reference: https://github.com/affaan-m/everything-claude-code',
+        'Scope: project-local standards for peaks-rd, peaks-qa, and peaks-solo workflow preflight.',
+        ''
+    ].join('\n');
+}
+function renderProjectStackSection(ctx) {
+    if (!ctx.hasPackageJson)
+        return '';
+    const lines = ['## Detected project stack', ''];
+    lines.push(`- Build tool: ${buildToolLabel(ctx.buildTool)}${ctx.buildConfigPath !== undefined ? ` (\`${ctx.buildConfigPath}\`)` : ''}`);
+    lines.push(`- Component library: ${componentLibraryLabel(ctx.componentLibrary)}`);
+    if (ctx.cssFrameworks.length > 0) {
+        lines.push(`- CSS: ${ctx.cssFrameworks.map(cssFrameworkLabel).join(', ')}`);
+    }
+    if (ctx.stateManagement.length > 0)
+        lines.push(`- State management: ${ctx.stateManagement.join(', ')}`);
+    if (ctx.routing.length > 0)
+        lines.push(`- Routing: ${ctx.routing.join(', ')}`);
+    if (ctx.dataFetching.length > 0)
+        lines.push(`- Data fetching: ${ctx.dataFetching.join(', ')}`);
+    if (ctx.notableDeps.length > 0)
+        lines.push(`- Notable deps: ${ctx.notableDeps.join(', ')}`);
+    lines.push('');
+    if (ctx.cssConflicts.length > 0) {
+        lines.push('## CSS framework conflicts', '');
+        for (const conflict of ctx.cssConflicts)
+            lines.push(`- ${conflict}`);
+        lines.push('');
+    }
+    if (ctx.legacySignals.length > 0) {
+        lines.push('## Legacy constraints (preserve for new code in the same modules)', '');
+        for (const signal of ctx.legacySignals)
+            lines.push(`- ${signal}`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function renderClaudeMd(language, ctx) {
+    const head = [
+        '# Project Instructions',
+        '',
+        '> 🤖 AI 生成，请审阅',
+        '',
+        'This repository uses project-local Peaks standards. Existing repository conventions override generic generated guidance.',
+        '',
+        'Peaks workflow automation:',
+        '- peaks-rd checks these standards before RD planning or implementation work.',
+        '- peaks-qa checks code review and security guidance before verification work.',
+        '- peaks-solo summarizes RD and QA standards preflight before end-to-end code workflows.',
+        '',
+        'Rules:',
+        '- Read `.claude/rules/common/coding-style.md` before editing code.',
+        '- Read `.claude/rules/common/code-review.md` before reviewing changes.',
+        '- Read `.claude/rules/common/security.md` before touching filesystem, user input, external calls, auth, or secrets.',
+        `- Read .claude/rules/${language}/coding-style.md for language-specific standards when applicable.`,
+        '',
+        'Active Peaks-Cli skill presence: at the start of every response, run `peaks skill presence --json` to read the active skill marker. The CLI handles canonical-path resolution (`.peaks/_runtime/active-skill.json` with back-compat fallback to `.peaks/.active-skill.json`); do not read those files directly. When the response includes a valid skill name, display the compact status header: `Peaks-Cli Skill: <skill> | Peaks-Cli Gate: <gate> | Next: <one short action>`. Display the header on every turn while the CLI returns an active skill; omit when the CLI returns no active skill.'
+    ].join('\n');
+    const stack = renderProjectStackSection(ctx);
+    return stack === '' ? head : `${head}\n${stack}`;
+}
+function renderCommonCodingStyle(ctx) {
+    const baseRules = [
+        '- Prefer simple, readable code over clever abstractions.',
+        '- Keep functions focused and files cohesive.',
+        '- Use immutable updates unless a language-specific convention explicitly favors mutation.',
+        '- Validate user input, external data, file paths, and configuration at system boundaries.',
+        '- Preserve existing project conventions when they are stricter than this baseline.'
+    ];
+    const stackRules = [];
+    const lib = ctx.componentLibrary.name;
+    if (lib === 'antd' || lib === 'antd-pro') {
+        const major = ctx.componentLibrary.majorVersion ?? '5';
+        stackRules.push(`- Use existing antd v${major} components (\`Button\`, \`Form\`, \`Table\`, \`Modal\`, \`Select\`). Never mix antd v3/v4/v5 APIs.`);
+        stackRules.push(`- Customize antd via \`theme.token\` / \`ConfigProvider\` / \`className\` / \`styles\`. Do NOT apply TailwindCSS utility classes directly to antd components.`);
+        if (ctx.componentLibrary.hasProSuite === true) {
+            stackRules.push('- Use `@ant-design/pro-components` (`ProTable`, `ProForm`, `ProLayout`) where the page is already pro-based — do not introduce a parallel non-pro table/form.');
+        }
+    }
+    if (lib === 'mui')
+        stackRules.push('- Style MUI via `sx`, `styled()`, and `theme`. Do NOT apply TailwindCSS utility classes directly to MUI components.');
+    if (ctx.cssFrameworks.includes('tailwind') && (lib === 'antd' || lib === 'antd-pro' || lib === 'mui')) {
+        stackRules.push('- TailwindCSS is for layout/utility only; component-library tokens own component styling.');
+    }
+    if (ctx.cssFrameworks.includes('less'))
+        stackRules.push('- Less variables in `src/theme/*.less` (or equivalent) are the canonical design tokens — extend them, do not hardcode colors/spacing.');
+    if (ctx.stateManagement.length > 0)
+        stackRules.push(`- Follow the existing state library (${ctx.stateManagement.join(', ')}); do not introduce a competing state library.`);
+    if (ctx.dataFetching.length > 0)
+        stackRules.push(`- Reuse the existing data-fetching pattern (${ctx.dataFetching.join(', ')}) for new API calls.`);
+    for (const signal of ctx.legacySignals)
+        stackRules.push(`- ${signal}`);
+    const rules = stackRules.length > 0 ? [...baseRules, '', '## Project-specific rules', ...stackRules] : baseRules;
+    return `${renderHeader('Common Coding Standards')}${rules.join('\n')}\n`;
+}
+function renderCodeReview(ctx) {
+    const baseRules = [
+        '- Review diffs for correctness, maintainability, test coverage, and regression risk.',
+        '- Treat missing tests for changed behavior as a blocker unless the change is documentation-only.',
+        '- Verify code paths that handle filesystem, external APIs, credentials, user input, or generated artifacts.',
+        '- peaks-qa must use this guidance as part of code workflow preflight and final verification.'
+    ];
+    const extra = [];
+    const lib = ctx.componentLibrary.name;
+    if (lib === 'antd' || lib === 'antd-pro') {
+        extra.push('- Block PRs that introduce a second component library (MUI/Chakra) alongside antd.');
+        extra.push('- Block PRs that import antd v3/v4 APIs in this v5 project, or vice versa.');
+    }
+    if (ctx.cssFrameworks.includes('tailwind') && (lib === 'antd' || lib === 'antd-pro' || lib === 'mui')) {
+        extra.push('- Flag Tailwind utility classes applied directly to component-library primitives; require component-library APIs instead.');
+    }
+    if (ctx.legacySignals.length > 0) {
+        extra.push('- Verify new code in legacy modules preserves the existing patterns (see `.claude/rules/common/coding-style.md` "Project-specific rules").');
+    }
+    const rules = extra.length > 0 ? [...baseRules, '', '## Project-specific review focus', ...extra] : baseRules;
+    return `${renderHeader('Code Review Standards')}${rules.join('\n')}\n`;
+}
+function renderSecurity(ctx) {
+    const baseRules = [
+        '- Never hardcode secrets, API keys, passwords, tokens, or credentials.',
+        '- Do not send private code or secrets to external services without explicit user authorization.',
+        '- Guard filesystem writes against path traversal, symlink, and junction escapes.',
+        '- Require explicit confirmation for destructive actions, external state changes, and credential use.'
+    ];
+    const extra = [];
+    if (ctx.buildTool === 'next')
+        extra.push('- Validate request body / query / params at every API route boundary (`pages/api/**` or `app/api/**`).');
+    if (ctx.dataFetching.length > 0)
+        extra.push(`- Sanitize and validate API responses before rendering or persisting (current fetchers: ${ctx.dataFetching.join(', ')}).`);
+    if (ctx.notableDeps.includes('monaco-editor') || ctx.notableDeps.includes('@monaco-editor/react')) {
+        extra.push('- Monaco editor content is untrusted; never `eval` or `Function`-construct user-authored code without an explicit, reviewed sandbox.');
+    }
+    const rules = extra.length > 0 ? [...baseRules, '', '## Project-specific security focus', ...extra] : baseRules;
+    return `${renderHeader('Security Review Standards')}${rules.join('\n')}\n`;
+}
+function renderLanguageCodingStyle(language, ctx) {
+    const languageName = language === 'generic' ? 'Generic' : language[0].toUpperCase() + language.slice(1);
+    const typeSafetyRule = language === 'typescript' || language === 'javascript'
+        ? '- Do not add new `any` types; use explicit domain types, generics, or `unknown` with narrowing.\n'
+        : '';
+    const baseRules = [
+        `- Apply project-local conventions before generic ${language} guidance.`,
+        `- Keep public APIs typed or documented according to ${language} ecosystem norms.`,
+        typeSafetyRule.trim() !== '' ? typeSafetyRule.trim() : null,
+        '- Prefer standard tooling and existing project scripts for formatting, linting, tests, and coverage.',
+        `- peaks-rd must check this file before planning code changes in ${language} projects.`
+    ].filter((line) => line !== null);
+    const extra = [];
+    if ((language === 'typescript' || language === 'javascript') && (ctx.componentLibrary.name === 'antd' || ctx.componentLibrary.name === 'antd-pro')) {
+        extra.push('- Type form values, table records, and API responses with named interfaces; do not rely on `Form.useForm()` inference for shared shapes.');
+    }
+    if ((language === 'typescript' || language === 'javascript') && ctx.dataFetching.includes('@tanstack/react-query')) {
+        extra.push('- Declare query/mutation generics (`useQuery<TData, TError>`) so consumers get typed data.');
+    }
+    if ((language === 'typescript' || language === 'javascript') && ctx.buildTool === 'umi') {
+        extra.push('- Use the project\'s existing service-layer pattern (`src/services/**`) for API calls; do not hand-roll `fetch` in components.');
+    }
+    const rules = extra.length > 0 ? [...baseRules, '', '## Project-specific rules', ...extra] : baseRules;
+    return `${renderHeader(`${languageName} Coding Standards`)}${rules.join('\n')}\n`;
+}
+function renderManagedClaudeMdIndex(language) {
+    return [
+        '<!-- peaks-standards:index:start -->',
+        '## Peaks Standards Index',
+        '- Constitution: `CLAUDE.md` is the repository-wide constitution.',
+        '- Local laws: `.claude/rules/**` are project-local laws and are created only when missing.',
+        '- Managed by: `peaks standards update`.',
+        '- Managed files:',
+        '  - `.claude/rules/common/code-review.md`',
+        '  - `.claude/rules/common/coding-style.md`',
+        '  - `.claude/rules/common/security.md`',
+        `  - .claude/rules/${language}/coding-style.md`,
+        '- Conflict note: keep the existing body unchanged and resolve any disagreement manually before the next standards update.',
+        '<!-- peaks-standards:index:end -->',
+        ''
+    ].join('\n');
+}
+function readFileIfExists(path) {
+    if (!existsSync(path))
+        return null;
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        return readFileSync(fd, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function getPendingStandardsRuleWrites(plan) {
+    return plan.plannedWrites.filter((write) => write.relativePath !== 'CLAUDE.md' && write.status !== 'existing');
+}
+function prevalidateWrites(projectRoot, writes, resolveHomedir = osHomedir) {
+    const homeRoot = resolveHomedir();
+    for (const write of writes) {
+        const targetPath = resolve(write.filePath);
+        const targetDir = dirname(targetPath);
+        assertWritablePathInsideProject(targetDir, projectRoot);
+        if (write.relativePath === 'CLAUDE.md') {
+            assertSafeClaudeMdPath(targetPath, projectRoot);
+        }
+        assertNotHomedirBaseline(targetPath, projectRoot, homeRoot);
+    }
+}
+function assertNotHomedirBaseline(targetPath, projectRoot, homeRoot) {
+    if (homeRoot === '' || projectRoot === '')
+        return;
+    const realProjectRoot = normalizeRoot(projectRoot);
+    const realHomeRoot = normalizeRoot(homeRoot);
+    // Canonical "rules wrote to global instead of project" bug: when the
+    // resolved projectRoot IS the user-level homedir, the planned write
+    // would land at `~/.claude/**`, polluting the baseline installed by
+    // `scripts/install-skills.mjs`. Defense in depth: never silently
+    // write to the user-level baseline.
+    //
+    // Note: we deliberately do NOT reject projects that are merely
+    // subdirectories of homedir (e.g. `~/Desktop/test/platform-rag-web`).
+    // Those are normal consumer projects; the writes go to
+    // `<projectRoot>/.claude/**`, NOT to `<homedir>/.claude/**`. The
+    // second check below is the real protection: it inspects whether the
+    // resolved write target itself lands inside `<homedir>/.claude/`,
+    // which only fires for the canonical bug case (or any accidental
+    // `~/` reference in the call chain that lands in `.claude/`).
+    if (realProjectRoot === realHomeRoot) {
+        throw new ProjectStandardsWriteTargetError({
+            filePath: targetPath,
+            projectRoot: realProjectRoot,
+            reason: 'resolves-to-homedir-claude'
+        });
+    }
+    // Reject if the resolved write target itself lands inside the
+    // homedir's `.claude/` tree. This catches accidental `~/` usage anywhere
+    // in the call chain even when projectRoot is sane. Walk up to the first
+    // existing ancestor so realpathSync does not ENOENT on a planned file.
+    const homeClaudeDir = join(realHomeRoot, '.claude');
+    const realHomeClaudeDir = existsSync(homeClaudeDir) ? realpathSync(homeClaudeDir) : homeClaudeDir;
+    let cursor = targetPath;
+    while (!existsSync(cursor)) {
+        const parent = dirname(cursor);
+        if (parent === cursor)
+            break;
+        cursor = parent;
+    }
+    if (!existsSync(cursor))
+        return; // Nothing on disk to inspect; the project-root check above already covered the case.
+    const realTargetAncestor = realpathSync(cursor);
+    if (isInsidePath(realTargetAncestor, realHomeClaudeDir)) {
+        throw new ProjectStandardsWriteTargetError({
+            filePath: realTargetAncestor,
+            projectRoot: realProjectRoot,
+            reason: 'resolves-to-homedir-claude'
+        });
+    }
+}
+function writeMissingStandardsRules(plan, writes = getPendingStandardsRuleWrites(plan)) {
+    const writtenFiles = [];
+    for (const write of writes) {
+        const targetPath = resolve(write.filePath);
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeNewFile(targetPath, write.content);
+        writtenFiles.push(write.relativePath);
+    }
+    return writtenFiles;
+}
+function createTemplates(language, ctx) {
+    return [
+        { relativePath: 'CLAUDE.md', content: renderClaudeMd(language, ctx) },
+        { relativePath: '.claude/rules/common/code-review.md', content: renderCodeReview(ctx) },
+        { relativePath: '.claude/rules/common/coding-style.md', content: renderCommonCodingStyle(ctx) },
+        { relativePath: '.claude/rules/common/security.md', content: renderSecurity(ctx) },
+        { relativePath: `.claude/rules/${language}/coding-style.md`, content: renderLanguageCodingStyle(language, ctx) }
+    ];
+}
+function createManagedClaudeBlock(language) {
+    return renderManagedClaudeMdIndex(language);
+}
+function buildClaudeUpdate(projectRoot, language, ctx) {
+    const filePath = resolve(projectRoot, 'CLAUDE.md');
+    assertSafeClaudeMdPath(filePath, projectRoot);
+    const existingContent = readFileIfExists(filePath);
+    const managedBlock = createManagedClaudeBlock(language);
+    if (existingContent === null) {
+        return {
+            relativePath: 'CLAUDE.md',
+            filePath,
+            status: 'planned',
+            content: `${renderClaudeMd(language, ctx).trimEnd()}\n\n${managedBlock}`,
+            appendBlock: '',
+            reviewSuggestions: []
+        };
+    }
+    const existingBlockStart = existingContent.indexOf('<!-- peaks-standards:index:start -->');
+    if (existingBlockStart < 0) {
+        return {
+            relativePath: 'CLAUDE.md',
+            filePath,
+            status: 'appended',
+            content: `${existingContent.trimEnd()}
+
+${managedBlock}`,
+            appendBlock: `
+
+${managedBlock}`,
+            reviewSuggestions: []
+        };
+    }
+    const existingManagedBlock = existingContent.slice(existingBlockStart).trimEnd();
+    if (existingManagedBlock === managedBlock.trimEnd()) {
+        return {
+            relativePath: 'CLAUDE.md',
+            filePath,
+            status: 'existing',
+            content: existingContent,
+            appendBlock: '',
+            reviewSuggestions: []
+        };
+    }
+    return {
+        relativePath: 'CLAUDE.md',
+        filePath,
+        status: 'review',
+        content: existingContent,
+        appendBlock: '',
+        reviewSuggestions: ['Existing CLAUDE.md already has a managed standards block. Review the managed block manually before changing it.']
+    };
+}
+function buildWrite(projectRoot, template) {
+    const filePath = resolve(projectRoot, template.relativePath);
+    return {
+        ...template,
+        filePath,
+        status: existsSync(filePath) ? 'existing' : 'planned'
+    };
+}
+function writeNewFile(path, content) {
+    const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        writeFileSync(fd, content, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function appendExistingFile(path, content) {
+    const fd = openSync(path, constants.O_WRONLY | constants.O_APPEND | constants.O_NOFOLLOW);
+    try {
+        writeFileSync(fd, content, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+export function createProjectStandardsInitPlan(options) {
+    const projectRoot = normalizeRoot(options.projectRoot);
+    assertSafeStandardsRoot(projectRoot);
+    const language = options.language === undefined ? detectLanguageInternal(projectRoot) : parseLanguage(options.language);
+    const ctx = detectProjectContext(projectRoot);
+    const plannedWrites = createTemplates(language, ctx).map((template) => buildWrite(projectRoot, template));
+    return {
+        apply: options.apply ?? false,
+        projectRoot,
+        language,
+        source: SOURCE,
+        skillPreflight: SKILL_PREFLIGHT,
+        plannedWrites
+    };
+}
+export function createProjectStandardsUpdatePlan(options) {
+    const basePlan = createProjectStandardsInitPlan(options);
+    const ctx = detectProjectContext(basePlan.projectRoot);
+    const claudeMd = buildClaudeUpdate(basePlan.projectRoot, basePlan.language, ctx);
+    return {
+        ...basePlan,
+        claudeMd
+    };
+}
+export function executeProjectStandardsInit(options) {
+    const plan = createProjectStandardsInitPlan(options);
+    const writtenFiles = [];
+    const resolveHomedir = options.resolveHomedir ?? osHomedir;
+    if (plan.apply) {
+        assertSafeStandardsRoot(plan.projectRoot);
+        const pendingWrites = plan.plannedWrites.filter((write) => write.status !== 'existing');
+        prevalidateWrites(plan.projectRoot, pendingWrites, resolveHomedir);
+        for (const write of pendingWrites) {
+            const targetPath = resolve(write.filePath);
+            mkdirSync(dirname(targetPath), { recursive: true });
+            writeNewFile(targetPath, write.content);
+            writtenFiles.push(write.relativePath);
+        }
+    }
+    return {
+        ...plan,
+        plannedWrites: plan.plannedWrites.map((write) => writtenFiles.includes(write.relativePath) ? { ...write, status: 'written' } : write),
+        writtenFiles
+    };
+}
+export function executeProjectStandardsUpdate(options) {
+    const plan = createProjectStandardsUpdatePlan(options);
+    const writtenFiles = [];
+    const appendedFiles = [];
+    const reviewSuggestions = [...plan.claudeMd.reviewSuggestions];
+    let claudeMd = { ...plan.claudeMd };
+    const resolveHomedir = options.resolveHomedir ?? osHomedir;
+    if (plan.apply) {
+        assertSafeStandardsRoot(plan.projectRoot);
+        const pendingRuleWrites = getPendingStandardsRuleWrites(plan);
+        prevalidateWrites(plan.projectRoot, pendingRuleWrites, resolveHomedir);
+        const targetPath = resolve(claudeMd.filePath);
+        prevalidateWrites(plan.projectRoot, [claudeMd], resolveHomedir);
+        writtenFiles.push(...writeMissingStandardsRules(plan, pendingRuleWrites));
+        if (claudeMd.status === 'planned') {
+            writeNewFile(targetPath, claudeMd.content);
+            writtenFiles.push(claudeMd.relativePath);
+            claudeMd = { ...claudeMd, status: 'written' };
+        }
+        else if (claudeMd.status === 'appended') {
+            appendExistingFile(targetPath, claudeMd.appendBlock);
+            appendedFiles.push(claudeMd.relativePath);
+        }
+    }
+    const plannedWrites = plan.plannedWrites.map((write) => {
+        if (write.relativePath === 'CLAUDE.md') {
+            return { ...write, status: claudeMd.status };
+        }
+        if (writtenFiles.includes(write.relativePath)) {
+            return { ...write, status: 'written' };
+        }
+        return write;
+    });
+    return {
+        ...plan,
+        claudeMd,
+        plannedWrites,
+        writtenFiles,
+        appendedFiles,
+        reviewSuggestions
+    };
+}
+export function summarizeProjectStandardsInitResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        language: result.language,
+        source: result.source,
+        skillPreflight: result.skillPreflight,
+        plannedWrites: result.plannedWrites.map((write) => ({ relativePath: write.relativePath, status: write.status })),
+        writtenFiles: result.writtenFiles,
+        skippedFiles: result.plannedWrites.filter((write) => write.status === 'existing').map((write) => write.relativePath)
+    };
+}
+export function summarizeProjectStandardsUpdateResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        language: result.language,
+        source: result.source,
+        skillPreflight: result.skillPreflight,
+        plannedWrites: result.plannedWrites.map((write) => ({ relativePath: write.relativePath, status: write.status })),
+        writtenFiles: result.writtenFiles,
+        appendedFiles: result.appendedFiles,
+        skippedFiles: result.plannedWrites.filter((write) => write.status === 'existing').map((write) => write.relativePath),
+        reviewSuggestions: result.reviewSuggestions,
+        claudeMd: {
+            relativePath: result.claudeMd.relativePath,
+            status: result.claudeMd.status,
+            reviewSuggestions: result.claudeMd.reviewSuggestions
+        }
+    };
+}

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

@@ -0,0 +1,69 @@
+import type { WorkspaceConfig } from '../config/config-types.js';
+export type TechWaveName = 'scan' | 'document' | 'review' | 'reducer';
+export type TechStatusValue = 'unavailable' | 'missing' | 'blocked' | 'approved';
+export type TechPlanRequest = {
+    sessionId: string;
+    goal: string;
+    swarm: boolean;
+    dryRun: true;
+    artifactWorkspacePath?: string;
+    workspace?: WorkspaceConfig;
+};
+export type TechWave = {
+    name: TechWaveName;
+    taskIds: string[];
+};
+export type TechTask = {
+    taskId: string;
+    wave: TechWaveName;
+    workerKind: string;
+    purpose: string;
+    inputs: string[];
+    outputs: string[];
+    dependsOn: string[];
+    conflictGroup: string;
+    briefPath: string;
+};
+export type TechPlanGraph = {
+    available: true;
+    sessionId: string;
+    goal: string;
+    swarm: boolean;
+    dryRun: true;
+    artifactRoot: string;
+    waves: TechWave[];
+    tasks: TechTask[];
+    outputs: {
+        taskGraph: string;
+        waveManifests: string[];
+        reviewChecklist: string;
+        approvalTemplate: string;
+    };
+    blockedReasons: string[];
+    nextActions: string[];
+};
+export type TechPlanPreview = {
+    available: false;
+    behavior: 'preview';
+    reason: string;
+    preview: Omit<TechPlanGraph, 'available'>;
+    nextActions: readonly string[];
+};
+export type TechPlanResult = TechPlanGraph | TechPlanPreview;
+export type TechStatus = {
+    sessionId: string;
+    status: TechStatusValue;
+    artifactRoot: string;
+    requiredArtifacts: string[];
+    missingArtifacts: string[];
+    approvalRecord: string | null;
+    blockedReasons: string[];
+    nextActions: string[];
+};
+export declare const TECH_REQUIRED_ARTIFACTS: readonly string[];
+export declare function createTechPlan(request: TechPlanRequest): TechPlanResult;
+export declare function getTechStatus(options: {
+    sessionId: string;
+    artifactWorkspacePath?: string;
+    workspace?: WorkspaceConfig;
+}): TechStatus;