peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/standards/missing-standards-detector.js

@@ -0,0 +1,170 @@
+/**
+ * Slice 2026-06-16-peaks-code-auto-scaffold (RD#7) — missing-standards-detector.
+ *
+ * Read-side companion to the `peaks standards init` / `peaks standards update`
+ * writers in `./project-standards-service.ts`. The writer KNOWS how to scaffold
+ * `.peaks/standards/{common,<language>}/` (2.0 canonical) from the curated
+ * baseline; this module detects when the consumer project's rules tree is
+ * missing or empty and emits a copy-pasteable diagnostic for the operator.
+ *
+ * Why a separate read module: the writer is `apply`-gated and write-bounded
+ * (it touches the filesystem via `prevalidateWrites`/`assertNotHomedirBaseline`).
+ * The detector is read-only and platform-aware (win32 path separators for
+ * Windows consumers) — coupling the two would force the writer to grow a
+ * read-only flag and a platform-switching argument.
+ *
+ * Cross-platform path rendering (AC6): the detector switches on
+ * `process.platform` and renders the project path with `path.sep` so Windows
+ * consumers see `C:\Users\<u>\project\.claude\rules\` verbatim rather than the
+ * POSIX form. The detection logic itself (readdirSync on `node:fs`) is
+ * platform-neutral.
+ *
+ * Once-per-session dedup (AC7): `peaks workspace init` writes a marker at
+ * `.peaks/_runtime/<sessionId>/.standards-checked` after the first detection
+ * pass. `detectMissingProjectStandards` does NOT consult the marker — that's
+ * the caller's responsibility (the CLI command decides whether to skip per
+ * AC7's "once per session" contract).
+ */
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, sep as pathSep } from 'node:path';
+const SUPPORTED_LANGUAGES = new Set([
+    'generic',
+    'typescript',
+    'javascript',
+    'python',
+    'go',
+    'rust'
+]);
+function normalizeProjectRoot(projectRoot) {
+    return isAbsolute(projectRoot) ? projectRoot : join(process.cwd(), projectRoot);
+}
+function renderForPlatform(projectRoot) {
+    // AC6: render with the platform-native separator. On win32 we replace '/'
+    // with '\\' in the project path; the rest of the path is constructed with
+    // the same separator via the literal '\\' join below.
+    //
+    // 2.0 canonical location: `<projectRoot>/.peaks/standards/`
+    // (slice 2026-07-15-missing-standards-on-fresh-project — the 2.0
+    // writer scaffolds the rules tree under `.peaks/standards/`, not
+    // the legacy `.claude/rules/`).
+    if (process.platform === 'win32') {
+        const nativeRoot = projectRoot.replace(/\//g, '\\');
+        return `${nativeRoot}\\.peaks\\standards`;
+    }
+    return `${projectRoot}/.peaks/standards`;
+}
+function hasPopulatedMarkdown(dir) {
+    if (!existsSync(dir))
+        return false;
+    const stat = statSync(dir);
+    if (!stat.isDirectory())
+        return false;
+    const entries = readdirSync(dir);
+    return entries.some((entry) => entry.toLowerCase().endsWith('.md'));
+}
+export function diagnoseStandardsTree(projectRoot, language) {
+    if (!SUPPORTED_LANGUAGES.has(language)) {
+        throw new Error(`Unsupported standards language: ${String(language)}`);
+    }
+    const normalizedRoot = normalizeProjectRoot(projectRoot);
+    const commonDir = join(normalizedRoot, '.peaks', 'standards', 'common');
+    const languageDir = language === 'generic'
+        ? null
+        : join(normalizedRoot, '.peaks', 'standards', language);
+    const commonOk = hasPopulatedMarkdown(commonDir);
+    const languageOk = languageDir === null ? true : hasPopulatedMarkdown(languageDir);
+    if (commonOk && languageOk) {
+        return { kind: 'complete' };
+    }
+    if (!commonOk) {
+        return { kind: 'common-missing' };
+    }
+    // common ok, language overlay empty/missing
+    return { kind: 'language-missing', language };
+}
+/**
+ * Detect whether a consumer project's `.peaks/standards/` tree (2.0
+ * canonical) is missing or empty.
+ *
+ * Rules (per PRD R2, slice 2026-07-15):
+ *   - `.peaks/standards/common/` MUST exist AND contain at least one
+ *     `.md` file.
+ *   - `.peaks/standards/<language>/` MUST exist AND contain at least one
+ *     `.md` file — except for `generic`, where the language dir is
+ *     OPTIONAL.
+ *
+ * Returns `{ missing: true, ... }` when either required dir is absent or
+ * empty. The diagnostic is always populated so the caller can surface the
+ * remediation hint unconditionally (the CLI uses the same string for both
+ * the stderr banner and the JSON envelope warning).
+ */
+export function detectMissingProjectStandards(projectRoot, language) {
+    if (!SUPPORTED_LANGUAGES.has(language)) {
+        throw new Error(`Unsupported standards language: ${String(language)}`);
+    }
+    const normalizedRoot = normalizeProjectRoot(projectRoot);
+    const renderedPath = renderForPlatform(normalizedRoot);
+    const diagnostic = diagnoseStandardsTree(projectRoot, language);
+    // Bug-01 fix (ice-cola surface check 2026-07-22): the previous
+    // remediation said "no project-local standards found" whenever EITHER
+    // common or the language overlay was empty, which misrepresented
+    // projects that have common populated but a missing language overlay
+    // (e.g. ice-cola has common/*.md + typescript/coding-style.md but no
+    // javascript/coding-style.md). The remediation now distinguishes the
+    // three kinds so the operator gets a precise hint.
+    let missing;
+    let remediation;
+    if (diagnostic.kind === 'complete') {
+        missing = false;
+        remediation = `Project-local standards already present at ${renderedPath}. Re-run \`peaks standards init --project ${normalizedRoot} --apply\` to refresh from the curated baseline.`;
+    }
+    else if (diagnostic.kind === 'common-missing') {
+        missing = true;
+        remediation = `⚠ no project-local common standards at ${renderedPath} — run \`peaks standards init --project ${normalizedRoot} --apply\` to scaffold (language: ${language}), or pass --init-standards to peaks workspace init for one-shot auto-apply.`;
+    }
+    else {
+        missing = true;
+        const overlayName = diagnostic.language;
+        remediation = `⚠ common standards present at ${renderedPath}\\common but ${overlayName} language overlay is missing — run \`peaks standards init --project ${normalizedRoot} --apply\` to scaffold the ${overlayName} overlay (or pass --init-standards to peaks workspace init for one-shot auto-apply).`;
+    }
+    return {
+        missing,
+        path: renderedPath,
+        remediation,
+        language
+    };
+}
+/**
+ * Once-per-session marker file path. The CLI writes this file under
+ * `.peaks/_runtime/<sessionId>/` after the first diagnostic pass so that
+ * subsequent `peaks workspace init` invocations within the same session
+ * skip the stderr banner (the diagnostic is still computable for
+ * programmatic consumers via `detectMissingProjectStandards`).
+ */
+export function getStandardsCheckedMarkerPath(projectRoot, sessionId) {
+    const normalizedRoot = normalizeProjectRoot(projectRoot);
+    // Canonical session runtime dir — see `.peaks/memory/session-dir-canonical-resolver-must-route-all-writes.md`.
+    return join(normalizedRoot, '.peaks', '_runtime', sessionId, '.standards-checked');
+}
+/**
+ * Mark this session as "standards checked" so subsequent invocations can
+ * skip the stderr diagnostic. Idempotent: existing marker is left as-is.
+ * Returns true if the marker was newly created, false if it already existed.
+ */
+export function markStandardsChecked(projectRoot, sessionId) {
+    const markerPath = getStandardsCheckedMarkerPath(projectRoot, sessionId);
+    if (existsSync(markerPath))
+        return false;
+    mkdirSync(join(markerPath, '..'), { recursive: true });
+    writeFileSync(markerPath, 'standards-checked\n', 'utf8');
+    return true;
+}
+/**
+ * Test seam: check whether the once-per-session marker exists. Caller is
+ * responsible for routing the result into the AC7 dedup logic.
+ */
+export function hasStandardsCheckedMarker(projectRoot, sessionId) {
+    return existsSync(getStandardsCheckedMarkerPath(projectRoot, sessionId));
+}
+// Re-export path.sep for tests that want to assert the platform invariant.
+export const platformPathSeparator = pathSep;

package/dist/services/standards/project-context.d.ts

@@ -0,0 +1,24 @@
+export type BuildTool = 'umi' | 'next' | 'vite' | 'rsbuild' | 'rspack' | 'farm' | 'craco' | 'webpack' | 'gulp' | 'angular' | 'custom' | 'unknown';
+export type ComponentLibrary = {
+    readonly name: 'antd' | 'antd-pro' | 'mui' | 'element-plus' | 'element-ui' | 'arco' | 'tdesign' | 'semi' | 'nextui' | 'chakra' | 'vant' | 'none';
+    readonly majorVersion?: string;
+    readonly hasProSuite?: boolean;
+};
+export type CssFramework = 'less' | 'sass' | 'tailwind' | 'css-modules' | 'styled-components' | 'emotion' | 'plain-css' | 'unknown';
+export type ProjectContext = {
+    readonly hasPackageJson: boolean;
+    readonly buildTool: BuildTool;
+    readonly buildConfigPath?: string;
+    readonly componentLibrary: ComponentLibrary;
+    readonly cssFrameworks: CssFramework[];
+    readonly cssConflicts: string[];
+    readonly stateManagement: string[];
+    readonly routing: string[];
+    readonly dataFetching: string[];
+    readonly legacySignals: string[];
+    readonly notableDeps: string[];
+};
+export declare function detectProjectContext(projectRoot: string): ProjectContext;
+export declare function buildToolLabel(tool: BuildTool): string;
+export declare function componentLibraryLabel(lib: ComponentLibrary): string;
+export declare function cssFrameworkLabel(framework: CssFramework): string;

package/dist/services/standards/project-context.js

@@ -0,0 +1,314 @@
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+function readPackageJson(projectRoot) {
+    const pkgPath = join(projectRoot, 'package.json');
+    if (!existsSync(pkgPath))
+        return { exists: false, deps: {} };
+    try {
+        const raw = readFileSync(pkgPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return {
+            exists: true,
+            deps: {
+                ...(parsed.dependencies ?? {}),
+                ...(parsed.devDependencies ?? {}),
+                ...(parsed.peerDependencies ?? {})
+            }
+        };
+    }
+    catch {
+        return { exists: true, deps: {} };
+    }
+}
+function configExists(projectRoot, candidates) {
+    for (const candidate of candidates) {
+        if (existsSync(join(projectRoot, candidate)))
+            return candidate;
+    }
+    return undefined;
+}
+function detectBuildTool(projectRoot) {
+    const map = [
+        ['umi', ['.umirc.ts', '.umirc.js', 'config/config.ts', 'config/config.js']],
+        ['next', ['next.config.js', 'next.config.ts', 'next.config.mjs']],
+        ['vite', ['vite.config.ts', 'vite.config.js', 'vite.config.mjs']],
+        ['rsbuild', ['rsbuild.config.ts', 'rsbuild.config.js']],
+        ['rspack', ['rspack.config.ts', 'rspack.config.js']],
+        ['farm', ['farm.config.ts', 'farm.config.js']],
+        ['craco', ['craco.config.js', 'craco.config.ts']],
+        ['webpack', ['webpack.config.js', 'webpack.config.ts']],
+        ['gulp', ['gulpfile.js', 'gulpfile.ts']],
+        ['angular', ['angular.json']]
+    ];
+    for (const [tool, candidates] of map) {
+        const found = configExists(projectRoot, candidates);
+        if (found !== undefined)
+            return { tool, path: found };
+    }
+    return { tool: 'unknown' };
+}
+function majorOf(version) {
+    if (version === undefined)
+        return undefined;
+    const cleaned = version.replace(/^[\^~>=<]+/, '').trim();
+    const major = cleaned.split('.')[0];
+    return major !== undefined && /^\d+$/.test(major) ? major : undefined;
+}
+function detectComponentLibrary(deps) {
+    if ('antd' in deps) {
+        const major = majorOf(deps['antd']);
+        const hasProSuite = '@ant-design/pro-components' in deps || Object.keys(deps).some((d) => d.startsWith('@ant-design/pro-'));
+        return hasProSuite
+            ? { name: 'antd-pro', ...(major !== undefined ? { majorVersion: major } : {}), hasProSuite: true }
+            : { name: 'antd', ...(major !== undefined ? { majorVersion: major } : {}) };
+    }
+    if ('@mui/material' in deps)
+        return { name: 'mui', ...(majorOf(deps['@mui/material']) !== undefined ? { majorVersion: majorOf(deps['@mui/material']) } : {}) };
+    if ('element-plus' in deps)
+        return { name: 'element-plus' };
+    if ('element-ui' in deps)
+        return { name: 'element-ui' };
+    if ('@arco-design/web-react' in deps)
+        return { name: 'arco' };
+    if ('tdesign-react' in deps || 'tdesign-vue-next' in deps)
+        return { name: 'tdesign' };
+    if ('@douyinfe/semi-ui' in deps)
+        return { name: 'semi' };
+    if ('@nextui-org/react' in deps)
+        return { name: 'nextui' };
+    if ('@chakra-ui/react' in deps)
+        return { name: 'chakra' };
+    if ('vant' in deps)
+        return { name: 'vant' };
+    return { name: 'none' };
+}
+function detectCssFrameworks(projectRoot, deps) {
+    const frameworks = [];
+    if ('tailwindcss' in deps || existsSync(join(projectRoot, 'tailwind.config.js')) || existsSync(join(projectRoot, 'tailwind.config.ts'))) {
+        frameworks.push('tailwind');
+    }
+    if ('less' in deps || 'less-loader' in deps)
+        frameworks.push('less');
+    if ('sass' in deps || 'node-sass' in deps || 'sass-loader' in deps)
+        frameworks.push('sass');
+    if ('styled-components' in deps)
+        frameworks.push('styled-components');
+    if ('@emotion/react' in deps || '@emotion/styled' in deps)
+        frameworks.push('emotion');
+    // css-modules detection is heuristic (Umi/Next default); skip unless we see *.module.* in src
+    return frameworks;
+}
+function detectCssConflicts(library, frameworks) {
+    const conflicts = [];
+    const hasTailwind = frameworks.includes('tailwind');
+    if (hasTailwind && (library.name === 'antd' || library.name === 'antd-pro')) {
+        conflicts.push("Tailwind preflight reset can break antd component base styles; set `corePlugins.preflight: false` in tailwind.config or scope Tailwind via `important: '#root'`.");
+    }
+    if (hasTailwind && library.name === 'mui') {
+        conflicts.push('Tailwind preflight overrides MUI base styles; disable Tailwind preflight or scope it away from MUI roots.');
+    }
+    const cssInJsCount = [frameworks.includes('styled-components'), frameworks.includes('emotion')].filter(Boolean).length;
+    if (cssInJsCount >= 2) {
+        conflicts.push('Multiple CSS-in-JS libraries detected (styled-components + emotion); pick one and remove the other.');
+    }
+    return conflicts;
+}
+function detectStateManagement(deps) {
+    const map = [
+        ['zustand', 'zustand'],
+        ['jotai', 'jotai'],
+        ['@reduxjs/toolkit', 'Redux Toolkit'],
+        ['redux', 'redux'],
+        ['valtio', 'valtio'],
+        ['mobx', 'mobx'],
+        ['hox', 'hox']
+    ];
+    return map.filter(([dep]) => dep in deps).map(([, label]) => label);
+}
+function detectRouting(deps) {
+    const out = [];
+    if ('react-router-dom' in deps)
+        out.push('react-router-dom');
+    if ('@umijs/max' in deps || '@umijs/preset-react' in deps)
+        out.push('Umi router');
+    if ('next' in deps)
+        out.push('Next.js file-based');
+    if ('vue-router' in deps)
+        out.push('vue-router');
+    return out;
+}
+function detectDataFetching(deps) {
+    const out = [];
+    if ('@tanstack/react-query' in deps)
+        out.push('@tanstack/react-query');
+    if ('swr' in deps)
+        out.push('swr');
+    if ('ahooks' in deps)
+        out.push('ahooks (useRequest)');
+    if ('umi-request' in deps)
+        out.push('umi-request');
+    if ('axios' in deps)
+        out.push('axios');
+    return out;
+}
+function detectLegacySignals(projectRoot, deps) {
+    const signals = [];
+    if ('moment' in deps)
+        signals.push('`moment` in deps — prefer `dayjs` or `date-fns` for new code');
+    if (Object.keys(deps).some((d) => d.startsWith('enzyme')))
+        signals.push('Enzyme test suite — write new tests with React Testing Library');
+    if ('redux-saga' in deps)
+        signals.push('redux-saga — keep saga patterns for existing flows; use Redux Toolkit thunks/RTK Query for new code');
+    if ('redux-thunk' in deps && !('@reduxjs/toolkit' in deps))
+        signals.push('Plain redux-thunk — prefer Redux Toolkit createAsyncThunk for new code');
+    if ('jquery' in deps)
+        signals.push('jQuery — do not add new jQuery usage');
+    if ('backbone' in deps)
+        signals.push('Backbone — legacy; do not add new Backbone code');
+    if (deps['vue']?.startsWith('2') === true)
+        signals.push('Vue 2 — preserve Options API for existing components');
+    // Lightweight heuristic for class components and inline styles in src/
+    const srcRoot = join(projectRoot, 'src');
+    if (existsSync(srcRoot)) {
+        const sample = sampleSourceFiles(srcRoot, 80);
+        let classComponentHits = 0;
+        let inlineStyleHits = 0;
+        for (const filePath of sample) {
+            try {
+                const content = readFileSync(filePath, 'utf8');
+                if (/extends\s+(?:React\.)?Component\b/.test(content))
+                    classComponentHits += 1;
+                const matches = content.match(/style=\{\{/g);
+                if (matches !== null)
+                    inlineStyleHits += matches.length;
+            }
+            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                // ignore unreadable files
+            }
+        }
+        if (classComponentHits >= 1)
+            signals.push(`React class components detected (${classComponentHits}+ files) — keep class style for existing modules, use function components + hooks for new code`);
+        if (inlineStyleHits >= 50)
+            signals.push(`Inline styles dominant (${inlineStyleHits}+ occurrences) — match existing styling for new code in same modules`);
+    }
+    return signals;
+}
+function sampleSourceFiles(root, limit) {
+    const out = [];
+    const queue = [root];
+    while (queue.length > 0 && out.length < limit) {
+        const dir = queue.shift();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.startsWith('.') || entry === 'node_modules' || entry === 'dist' || entry === 'build')
+                continue;
+            const full = join(dir, entry);
+            let s;
+            try {
+                s = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (s.isDirectory()) {
+                queue.push(full);
+            }
+            else if (/\.(tsx|jsx)$/.test(entry)) {
+                out.push(full);
+                if (out.length >= limit)
+                    break;
+            }
+        }
+    }
+    return out;
+}
+function notableDepsList(deps) {
+    const interesting = ['monaco-editor', '@monaco-editor/react', 'react-querybuilder', '@dnd-kit/core', 'react-dnd', 'echarts', 'recharts', '@ant-design/charts', 'antd-style', 'lodash', 'lodash-es', 'rxjs', 'socket.io-client'];
+    return interesting.filter((d) => d in deps);
+}
+export function detectProjectContext(projectRoot) {
+    const { exists, deps } = readPackageJson(projectRoot);
+    const { tool, path } = detectBuildTool(projectRoot);
+    const componentLibrary = detectComponentLibrary(deps);
+    const cssFrameworks = detectCssFrameworks(projectRoot, deps);
+    return {
+        hasPackageJson: exists,
+        buildTool: tool,
+        ...(path !== undefined ? { buildConfigPath: path } : {}),
+        componentLibrary,
+        cssFrameworks,
+        cssConflicts: detectCssConflicts(componentLibrary, cssFrameworks),
+        stateManagement: detectStateManagement(deps),
+        routing: detectRouting(deps),
+        dataFetching: detectDataFetching(deps),
+        legacySignals: detectLegacySignals(projectRoot, deps),
+        notableDeps: notableDepsList(deps)
+    };
+}
+export function buildToolLabel(tool) {
+    const labels = {
+        umi: 'Umi',
+        next: 'Next.js',
+        vite: 'Vite',
+        rsbuild: 'Rsbuild',
+        rspack: 'Rspack',
+        farm: 'Farm',
+        craco: 'CRA + craco',
+        webpack: 'Webpack',
+        gulp: 'Gulp (legacy)',
+        angular: 'Angular',
+        custom: 'Custom build pipeline',
+        unknown: 'unknown'
+    };
+    return labels[tool];
+}
+export function componentLibraryLabel(lib) {
+    const base = (() => {
+        switch (lib.name) {
+            case 'antd':
+                return 'Ant Design';
+            case 'antd-pro':
+                return 'Ant Design + Ant Design Pro';
+            case 'mui':
+                return 'Material UI';
+            case 'element-plus':
+                return 'Element Plus';
+            case 'element-ui':
+                return 'Element UI';
+            case 'arco':
+                return 'Arco Design';
+            case 'tdesign':
+                return 'TDesign';
+            case 'semi':
+                return 'Semi Design';
+            case 'nextui':
+                return 'NextUI';
+            case 'chakra':
+                return 'Chakra UI';
+            case 'vant':
+                return 'Vant (mobile)';
+            case 'none':
+                return 'no component library detected';
+        }
+    })();
+    return lib.majorVersion !== undefined ? `${base} v${lib.majorVersion}` : base;
+}
+export function cssFrameworkLabel(framework) {
+    const labels = {
+        less: 'Less',
+        sass: 'Sass/SCSS',
+        tailwind: 'TailwindCSS',
+        'css-modules': 'CSS Modules',
+        'styled-components': 'styled-components',
+        emotion: 'Emotion',
+        'plain-css': 'plain CSS',
+        unknown: 'unknown'
+    };
+    return labels[framework];
+}

package/dist/services/standards/project-standards-service.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Typed error raised when a planned `peaks standards` write target would
+ * land outside `projectRoot` (or collide with the user-level baseline
+ * under `<homedir>/.claude/**`). Surfaced as a stable error code so CLI
+ * callers can map it to a recoverable hint.
+ */
+export type ProjectStandardsWriteTargetReason = 'outside-project-root' | 'resolves-to-homedir-claude';
+export declare class ProjectStandardsWriteTargetError extends Error {
+    readonly code: "PROJECT_STANDARDS_WRITE_TARGET_OUTSIDE_ROOT";
+    readonly filePath: string;
+    readonly projectRoot: string;
+    readonly reason: ProjectStandardsWriteTargetReason;
+    constructor(input: {
+        readonly filePath: string;
+        readonly projectRoot: string;
+        readonly reason: ProjectStandardsWriteTargetReason;
+    });
+}
+export type StandardsLanguage = 'generic' | 'typescript' | 'javascript' | 'python' | 'go' | 'rust';
+export type StandardsWriteStatus = 'planned' | 'existing' | 'written' | 'appended' | 'review';
+export type StandardsWrite = {
+    readonly relativePath: string;
+    readonly filePath: string;
+    readonly content: string;
+    readonly status: StandardsWriteStatus;
+};
+export type ProjectStandardsSource = {
+    readonly sourceId: 'everything-claude-code';
+    readonly url: 'https://github.com/affaan-m/everything-claude-code';
+    readonly usage: 'curated-baseline-reference';
+};
+export type StandardsSkillPreflight = {
+    readonly appliesTo: readonly ['peaks-rd', 'peaks-qa', 'peaks-code'];
+    readonly summary: string;
+};
+export type ProjectStandardsInitPlan = {
+    readonly apply: boolean;
+    readonly projectRoot: string;
+    readonly language: StandardsLanguage;
+    readonly source: ProjectStandardsSource;
+    readonly skillPreflight: StandardsSkillPreflight;
+    readonly plannedWrites: StandardsWrite[];
+};
+export type ProjectStandardsInitResult = ProjectStandardsInitPlan & {
+    readonly writtenFiles: string[];
+};
+export type ProjectStandardsInitSummary = {
+    readonly apply: boolean;
+    readonly projectRoot: string;
+    readonly language: StandardsLanguage;
+    readonly source: ProjectStandardsSource;
+    readonly skillPreflight: StandardsSkillPreflight;
+    readonly plannedWrites: Array<Pick<StandardsWrite, 'relativePath' | 'status'>>;
+    readonly writtenFiles: string[];
+    readonly skippedFiles: string[];
+};
+export type ProjectStandardsUpdatePlan = ProjectStandardsInitPlan & {
+    readonly claudeMd: {
+        readonly relativePath: 'CLAUDE.md';
+        readonly filePath: string;
+        readonly status: StandardsWriteStatus;
+        readonly content: string;
+        readonly appendBlock: string;
+        readonly reviewSuggestions: string[];
+    };
+};
+export type ProjectStandardsUpdateResult = ProjectStandardsUpdatePlan & {
+    readonly writtenFiles: string[];
+    readonly appendedFiles: string[];
+    readonly reviewSuggestions: string[];
+};
+export type ProjectStandardsUpdateSummary = {
+    readonly apply: boolean;
+    readonly projectRoot: string;
+    readonly language: StandardsLanguage;
+    readonly source: ProjectStandardsSource;
+    readonly skillPreflight: StandardsSkillPreflight;
+    readonly plannedWrites: Array<Pick<StandardsWrite, 'relativePath' | 'status'>>;
+    readonly writtenFiles: string[];
+    readonly appendedFiles: string[];
+    readonly skippedFiles: string[];
+    readonly reviewSuggestions: string[];
+    readonly claudeMd: {
+        readonly relativePath: 'CLAUDE.md';
+        readonly status: StandardsWriteStatus;
+        readonly reviewSuggestions: string[];
+    };
+};
+export type ProjectStandardsInitOptions = {
+    readonly projectRoot: string;
+    readonly language?: string;
+    readonly apply?: boolean;
+    /**
+     * Test seam: override the homedir resolver used by the
+     * write-target containment guard. Defaults to `os.homedir()`.
+     * Production callers should NOT pass this — it exists so unit
+     * tests can simulate the "projectRoot === homedir" trap without
+     * mutating global Node state (which is read-only).
+     */
+    readonly resolveHomedir?: () => string;
+};
+/**
+ * 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 declare function detectLanguage(projectRoot: string): StandardsLanguage;
+export declare function createProjectStandardsInitPlan(options: ProjectStandardsInitOptions): ProjectStandardsInitPlan;
+export declare function createProjectStandardsUpdatePlan(options: ProjectStandardsInitOptions): ProjectStandardsUpdatePlan;
+export declare function executeProjectStandardsInit(options: ProjectStandardsInitOptions): ProjectStandardsInitResult;
+export declare function executeProjectStandardsUpdate(options: ProjectStandardsInitOptions): ProjectStandardsUpdateResult;
+export declare function summarizeProjectStandardsInitResult(result: ProjectStandardsInitResult): ProjectStandardsInitSummary;
+export declare function summarizeProjectStandardsUpdateResult(result: ProjectStandardsUpdateResult): ProjectStandardsUpdateSummary;