peaks-loop 4.0.0-beta.2 → 4.0.0-beta.21

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

@@ -1,574 +0,0 @@
-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-code'],
-    summary: 'peaks-rd、peaks-qa、peaks-code 进入代码仓工作流时自动 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-code 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-code 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-Loop 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-Loop Skill: <skill> | Peaks-Loop 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/understand/understand-hybrid-service.js

@@ -1,100 +0,0 @@
-import { createCodegraphInvocation, executeCodegraphInvocation } from '../codegraph/codegraph-service.js';
-import { scanUnderstandAnything, summarizeKnowledgeGraph } from './understand-scan-service.js';
-import { getErrorMessage } from '../../shared/result.js';
-const DEFAULT_FILES = ['src/index.ts', 'package.json', 'README.md'];
-function resolveFiles(files) {
-    if (files !== undefined && files.length > 0) {
-        return [...files];
-    }
-    return [...DEFAULT_FILES];
-}
-async function safeSummarize(options) {
-    try {
-        return { summary: await summarizeKnowledgeGraph(options) };
-    }
-    catch (error) {
-        return { warning: `UA summary failed: ${getErrorMessage(error)}` };
-    }
-}
-async function runCodegraph(projectRoot, files, runner) {
-    try {
-        const invocation = createCodegraphInvocation({
-            subcommand: 'affected',
-            project: projectRoot,
-            files,
-            json: true
-        });
-        const execution = await executeCodegraphInvocation(invocation, runner);
-        if (execution.exitCode !== 0) {
-            return { warning: `codegraph affected exited with code ${execution.exitCode}: ${execution.stderr.slice(0, 200)}` };
-        }
-        let payload = null;
-        let parseError;
-        try {
-            payload = JSON.parse(execution.stdout);
-        }
-        catch (error) {
-            parseError = getErrorMessage(error);
-        }
-        return {
-            block: {
-                invocation: { subcommand: 'affected', files },
-                execution,
-                payload,
-                ...(parseError !== undefined ? { parseError } : {})
-            }
-        };
-    }
-    catch (error) {
-        return { warning: `codegraph affected failed: ${getErrorMessage(error)}` };
-    }
-}
-function decideSource(uaScan, hasCodegraph) {
-    const uaPresent = uaScan.exists && uaScan.graph.exists && uaScan.graph.parseError === undefined;
-    if (uaPresent && hasCodegraph)
-        return 'ua-and-codegraph-hybrid';
-    if (uaPresent)
-        return 'ua-only';
-    if (hasCodegraph)
-        return 'ua-missing-fallback-codegraph';
-    return 'both-missing';
-}
-export async function buildUnderstandContext(options) {
-    const startedAt = Date.now();
-    const files = resolveFiles(options.files);
-    const sampleSize = options.sampleSize ?? 5;
-    const warnings = [];
-    const scanOptions = { projectRoot: options.projectRoot };
-    if (options.artifactDir !== undefined) {
-        scanOptions.artifactDir = options.artifactDir;
-    }
-    const uaScan = await scanUnderstandAnything(scanOptions);
-    const uaSummaryPromise = uaScan.exists && uaScan.graph.exists
-        ? safeSummarize({ projectRoot: options.projectRoot, sampleSize, ...(options.artifactDir !== undefined ? { artifactDir: options.artifactDir } : {}) })
-        : Promise.resolve({});
-    const [uaSummary, codegraphResult] = await Promise.all([
-        uaSummaryPromise,
-        runCodegraph(options.projectRoot, files, options.codegraphRunner)
-    ]);
-    if (uaSummary.warning)
-        warnings.push(uaSummary.warning);
-    if (codegraphResult.warning)
-        warnings.push(codegraphResult.warning);
-    const source = decideSource(uaScan, codegraphResult.block !== undefined);
-    const result = {
-        projectRoot: options.projectRoot,
-        source,
-        durationMs: Date.now() - startedAt,
-        warnings
-    };
-    if (source === 'ua-only' || source === 'ua-and-codegraph-hybrid') {
-        result.ua = {
-            scan: uaScan,
-            ...(uaSummary.summary !== undefined ? { summary: uaSummary.summary } : {})
-        };
-    }
-    if (codegraphResult.block) {
-        result.codegraph = codegraphResult.block;
-    }
-    return result;
-}