peaks-cli 1.0.18 → 1.0.20

package/dist/src/services/artifacts/artifact-prerequisites.d.ts

@@ -8,6 +8,8 @@ export type ArtifactPrerequisite = {
     relativePath: string;
     /** Human-readable description of what this artifact represents. */
     description: string;
+    /** Optional content markers — when set, the file must contain ALL of these (case-insensitive substring). */
+    mustContain?: ReadonlyArray<string>;
 };
 export type PrerequisiteCheckResult = {
     ok: boolean;

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

@@ -1,4 +1,5 @@
 import { join } from 'node:path';
+import { readFile } from 'node:fs/promises';
 import { pathExists } from '../../shared/fs.js';
 export const VALID_REQUEST_TYPES = [
     'feature',
@@ -21,7 +22,16 @@ const TEST_CASES = { relativePath: 'qa/test-cases/<rid>.md', description: 'Gener
 const TEST_REPORT = { relativePath: 'qa/test-reports/<rid>.md', description: 'Test execution report with actual pass/fail/coverage results' };
 const SECURITY_FINDINGS = { relativePath: 'qa/security-findings.md', description: 'Security test findings (record "no findings" inside if truly clean)' };
 const PERFORMANCE_FINDINGS = { relativePath: 'qa/performance-findings.md', description: 'Performance test findings (record baseline/after numbers or explicit "not applicable" rationale)' };
+// PRD content prereq: ensures the PRD artifact has actual scope/acceptance content
+// before handoff to RD/UI/QA. The SKILL says "Handoff to RD/UI/QA is blocked while
+// the artifact is missing or in `draft` state" — this gives that claim a CLI gate.
+const PRD_CONTENT = {
+    relativePath: 'prd/requests/<rid>.md',
+    description: 'PRD artifact must contain Goal and Acceptance criteria sections before handoff',
+    mustContain: ['## Goals', '## Acceptance']
+};
 const FEATURE_TABLE = {
+    'prd:handed-off': [PRD_CONTENT],
     'rd:implemented': [TECH_DOC],
     'rd:qa-handoff': [TECH_DOC, CODE_REVIEW, SECURITY_REVIEW],
     'qa:running': [TEST_CASES],
@@ -30,6 +40,7 @@ const FEATURE_TABLE = {
 // Bugfix: lighter planning artifact (bug-analysis instead of tech-doc), still requires code review + security review + regression test.
 // Performance findings not mandatory for non-perf bugs (use --allow-incomplete --reason if a perf bug requires it).
 const BUGFIX_TABLE = {
+    'prd:handed-off': [PRD_CONTENT],
     'rd:implemented': [BUG_ANALYSIS],
     'rd:qa-handoff': [BUG_ANALYSIS, CODE_REVIEW, SECURITY_REVIEW],
     'qa:running': [TEST_CASES],
@@ -41,6 +52,7 @@ const REFACTOR_TABLE = FEATURE_TABLE;
 const NO_GATES = {};
 // Config: security review is the only mandatory check (config changes can break auth, CORS, CSP, secrets handling).
 const CONFIG_TABLE = {
+    'prd:handed-off': [PRD_CONTENT],
     'rd:qa-handoff': [SECURITY_REVIEW],
     'qa:verdict-issued': [SECURITY_FINDINGS]
 };
@@ -71,6 +83,18 @@ export async function checkPrerequisites(options) {
         const absolute = join(sessionRoot, relative);
         if (!(await pathExists(absolute))) {
             missing.push({ path: relative, description: prerequisite.description });
+            continue;
+        }
+        if (prerequisite.mustContain && prerequisite.mustContain.length > 0) {
+            const body = await readFile(absolute, 'utf8');
+            const lowered = body.toLowerCase();
+            const missingMarkers = prerequisite.mustContain.filter((marker) => !lowered.includes(marker.toLowerCase()));
+            if (missingMarkers.length > 0) {
+                missing.push({
+                    path: relative,
+                    description: `${prerequisite.description} — missing section(s): ${missingMarkers.join(', ')}`
+                });
+            }
         }
     }
     return { ok: missing.length === 0, missing };

package/dist/src/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' | 'shadcn' | '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/src/services/standards/project-context.js

@@ -0,0 +1,318 @@
+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 ('tailwindcss' in deps && Object.keys(deps).some((d) => d.startsWith('@radix-ui/')))
+        return { name: 'shadcn' };
+    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 {
+                // 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 'shadcn':
+                return 'shadcn/ui (Tailwind + Radix)';
+            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/src/services/standards/project-standards-service.js

@@ -1,5 +1,6 @@
 import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, realpathSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { buildToolLabel, componentLibraryLabel, cssFrameworkLabel, detectProjectContext } from './project-context.js';
 const SOURCE = {
     sourceId: 'everything-claude-code',
     url: 'https://github.com/affaan-m/everything-claude-code',
@@ -82,8 +83,40 @@ function renderHeader(title) {
         ''
     ].join('\n');
 }
-function renderClaudeMd(language) {
-    return [
+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 生成，请审阅',
@@ -104,39 +137,109 @@ function renderClaudeMd(language) {
         'External reference: https://github.com/affaan-m/everything-claude-code is used as a curated reference only. Do not execute or install external content without explicit approval.',
         ''
     ].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 (lib === 'shadcn')
+        stackRules.push('- Use existing shadcn component variants and Tailwind utility classes. Do not introduce a competing component library.');
+    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/shadcn/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 renderCommonCodingStyle() {
-    return `${renderHeader('Common Coding Standards')}- 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.
-`;
-}
-function renderCodeReview() {
-    return `${renderHeader('Code Review Standards')}- 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.
-`;
-}
-function renderSecurity() {
-    return `${renderHeader('Security Review Standards')}- 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.
-`;
-}
-function renderLanguageCodingStyle(language) {
+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'
         : '';
-    return `${renderHeader(`${languageName} Coding Standards`)}- Apply project-local conventions before generic ${language} guidance.
-- Keep public APIs typed or documented according to ${language} ecosystem norms.
-${typeSafetyRule}- 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.
-`;
+    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 [
@@ -189,19 +292,19 @@ function writeMissingStandardsRules(plan, writes = getPendingStandardsRuleWrites
     }
     return writtenFiles;
 }
-function createTemplates(language) {
+function createTemplates(language, ctx) {
     return [
-        { relativePath: 'CLAUDE.md', content: renderClaudeMd(language) },
-        { relativePath: '.claude/rules/common/code-review.md', content: renderCodeReview() },
-        { relativePath: '.claude/rules/common/coding-style.md', content: renderCommonCodingStyle() },
-        { relativePath: '.claude/rules/common/security.md', content: renderSecurity() },
-        { relativePath: `.claude/rules/${language}/coding-style.md`, content: renderLanguageCodingStyle(language) }
+        { 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) {
+function buildClaudeUpdate(projectRoot, language, ctx) {
     const filePath = resolve(projectRoot, 'CLAUDE.md');
     assertSafeClaudeMdPath(filePath, projectRoot);
     const existingContent = readFileIfExists(filePath);
@@ -211,7 +314,7 @@ function buildClaudeUpdate(projectRoot, language) {
             relativePath: 'CLAUDE.md',
             filePath,
             status: 'planned',
-            content: `${renderClaudeMd(language).trimEnd()}\n\n${managedBlock}`,
+            content: `${renderClaudeMd(language, ctx).trimEnd()}\n\n${managedBlock}`,
             appendBlock: '',
             reviewSuggestions: []
         };
@@ -281,7 +384,8 @@ export function createProjectStandardsInitPlan(options) {
     const projectRoot = normalizeRoot(options.projectRoot);
     assertSafeStandardsRoot(projectRoot);
     const language = options.language === undefined ? detectLanguage(projectRoot) : parseLanguage(options.language);
-    const plannedWrites = createTemplates(language).map((template) => buildWrite(projectRoot, template));
+    const ctx = detectProjectContext(projectRoot);
+    const plannedWrites = createTemplates(language, ctx).map((template) => buildWrite(projectRoot, template));
     return {
         apply: options.apply ?? false,
         projectRoot,
@@ -293,7 +397,8 @@ export function createProjectStandardsInitPlan(options) {
 }
 export function createProjectStandardsUpdatePlan(options) {
     const basePlan = createProjectStandardsInitPlan(options);
-    const claudeMd = buildClaudeUpdate(basePlan.projectRoot, basePlan.language);
+    const ctx = detectProjectContext(basePlan.projectRoot);
+    const claudeMd = buildClaudeUpdate(basePlan.projectRoot, basePlan.language, ctx);
     return {
         ...basePlan,
         claudeMd

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

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.0.18";
+export declare const CLI_VERSION = "1.0.20";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.0.18";
+export const CLI_VERSION = "1.0.20";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-qa/SKILL.md

@@ -34,9 +34,9 @@ Every QA invocation — feature, bug, refactor, clarification — must write **t
 
 | # | File | Path | Reader | Content |
 |---|------|------|--------|---------|
-| 1 | Test cases | `.peaks/<id>/qa/test-cases/<rid>.md` | RD (before impl), QA | Generated test scenarios with status |
-| 2 | Test report | `.peaks/<id>/qa/test-reports/<rid>.md` | QA, SC, Solo | Summary, coverage%, security, perf, risks |
-| 3 | Request artifact | `.peaks/<id>/qa/requests/<rid>.md` | Solo, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
+| 1 | Test cases | `.peaks/<session-id>/qa/test-cases/<request-id>.md` | RD (before impl), QA | Generated test scenarios with status |
+| 2 | Test report | `.peaks/<session-id>/qa/test-reports/<request-id>.md` | QA, SC, Solo | Summary, coverage%, security, perf, risks |
+| 3 | Request artifact | `.peaks/<session-id>/qa/requests/<request-id>.md` | Solo, RD↔QA loop | Verdict, boundary check, links to #1 and #2 |
 
 Concrete template and rules: `references/artifact-per-request.md`.
 
@@ -85,6 +85,16 @@ peaks openspec validate <change-id> --project <repo> --prefer-external --json
 peaks mcp list --json
 peaks mcp plan  --capability playwright-mcp.browser-validation --json
 peaks mcp apply --capability playwright-mcp.browser-validation --yes --json
+# DEV-SERVER REQUIREMENT (BLOCKING): a running dev server is REQUIRED for browser E2E.
+# Start the dev server (npm run dev / pnpm dev / umi dev / etc) and capture the actual
+# advertised URL from its stdout (do NOT hard-code localhost:8000). If the dev server
+# fails to start, hangs, or times out (e.g. tailwindcss/plugin slowness, port conflict,
+# missing env), this is a BLOCKER — NOT a reason to skip browser E2E. You MUST:
+#   1. Record the failure and root cause in qa/test-reports/<rid>.md;
+#   2. Return verdict=blocked (or return-to-rd if the root cause is implementation-related);
+#   3. NEVER substitute a production build (`umi build` / `vite build` / `next build`) for
+#      browser E2E. A successful production build proves compilation, not runtime behavior,
+#      and does NOT satisfy Gate D. Treating prod build as a fallback is a workflow violation.
 # Playwright MCP MUST simulate real user operations — not just take static screenshots.
 # The minimum interaction sequence for every frontend page/flow:
 #   mcp__playwright__browser_navigate         → URL (after allow-list), launches headed browser
@@ -221,6 +231,10 @@ ls .peaks/<id>/qa/screenshots/*.png 2>&1
 # Expected: one or more .png files
 # "No such file" → BLOCKED. Playwright MCP was not used or screenshots not saved.
 # Screenshots, logs, manual steps, or other tools must NOT substitute for this gate.
+# A successful production build (`umi build` / `vite build` / `next build` exit 0) does
+# NOT substitute for this gate. Compilation success ≠ runtime behavior.
+# If the dev server cannot start, verdict MUST be `blocked` (or `return-to-rd`),
+# NOT `pass`. Record the dev-server failure root cause in the test report.
 # Re-run frontend browser validation (step 7 in runbook) and save screenshots.
 ```
 ```bash

package/skills/peaks-rd/SKILL.md

@@ -442,11 +442,29 @@ Before RD work stops, finishes, blocks, or hands off to another role, emit a sho
 
 **Matt Pocock skills** (`diagnose`, `triage`, `tdd`, `improve-codebase-architecture`, `prototype`): Engineering references only. Inspect before applying; Peaks RD gates remain authoritative.
 
+## Matt Pocock skills integration
+
+Engineering methods from `mattpocock/skills` can inform RD work but never replace Peaks gates. Inspect upstream skill content before applying any method.
+
+- `diagnose` — root-cause investigation before fixing
+- `triage` — prioritize bug surface area
+- `tdd` — drive implementation from failing tests
+- `improve-codebase-architecture` — opportunistic refactor framing
+- `prototype` — throwaway exploration before committing to a slice
+
+These are references only; Peaks RD gates remain authoritative for handoff, acceptance, and slice closure.
+
 **Understand Anything**: Consume via `peaks understand status/show --json`. Fall back to `peaks codegraph context` or local project scan when absent.
 
 **Codegraph**: Optional local analysis via `peaks codegraph context/affected`. Output as untrusted supporting evidence; never commit `.codegraph/` artifacts.
 
-**Other external resources** (Context7, SearchCode, everything-claude-code, GitNexus, etc.): Use `peaks capabilities --source access-repo/mcp-server --json` before recommending. Reference-only, no execute/install/persist. Peaks RD gates remain authoritative.
+## Codegraph project analysis
+
+RD may use `peaks codegraph affected --project <path> <changed-files...> --json` as local project-analysis evidence to inform red-line scope boundaries before writing tech-doc or starting implementation. Treat the output as untrusted supporting evidence — verify against the actual code before relying on it.
+
+Do not run upstream installer flows, mutate agent settings, or commit `.codegraph/` artifacts. Peaks RD gates remain authoritative for handoff and acceptance.
+
+**Other external resources** (Context7, SearchCode, everything-claude-code, GitNexus, etc.): Use `peaks capabilities --source access-repo/mcp-server --json` for capability discovery before recommending. References only — do not execute upstream installers, do not install upstream resources, do not persist sensitive examples. Peaks RD gates remain authoritative.
 
 **OpenSpec and MCP CLI**: Route through Peaks CLI (`peaks openspec show/to-rd/render`, `peaks mcp list/plan/apply/call`). Do not hand-edit `openspec/changes/**` or `~/.claude/settings.json`. Recipes: `references/openspec-mcp-cli.md`.
 

package/skills/peaks-solo/SKILL.md

@@ -71,7 +71,7 @@ Use the Peaks CLI for runtime side effects.
 
 Map gstack stages to Peaks role artifacts; preserve Peaks confirmation gates. Do not delegate orchestration to gstack commands.
 
-For frontend workflows, RD and QA must use Playwright MCP for real browser E2E (`peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes`). Chrome DevTools MCP is a secondary CDP surface only. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). See `references/browser-workflow.md`.
+For frontend workflows, RD and QA must use Playwright MCP (`mcp__playwright__` tool namespace) for real browser E2E (`peaks mcp plan/apply --capability playwright-mcp.browser-validation --yes`). Chrome DevTools MCP is a secondary CDP surface only. Sanitize browser artifacts before retention (no login URLs, cookies, tokens, PII). See `references/browser-workflow.md`.
 
 ## Local intermediate artifact workspace (MANDATORY)
 
@@ -464,6 +464,7 @@ ls .peaks/<id>/qa/requests/<rid>.md
 find .peaks/<id>/ -type f | sort
 # Verify: files from gates A-D all appear in this list.
 # Any mandatory file missing → NOT complete. Do not emit TXT.
+# Gate G (CLAUDE.md + .claude/rules/**) must ALSO pass before TXT is emitted.
 ```
 
 **Gate F — Root pollution check (BLOCKING before completion):**
@@ -483,6 +484,25 @@ find . -maxdepth 1 -name "*.png" -o -name "*.jpg" -o -name "qa-*.js" -o -name "m
 # Legitimate project files (e.g. favicon.png) are fine — only move Peaks artifacts.
 ```
 
+**Gate G — Project standards present (BLOCKING before workflow completion):**
+```bash
+# After `peaks standards init/update --apply`, verify the files actually landed
+# at the project root. The CLAUDE.md and rules files are required so that
+# subsequent peaks-rd / peaks-qa / peaks-solo runs perform the project-local
+# preflight described in CLAUDE.md (read coding-style.md, code-review.md, security.md).
+ls <repo>/CLAUDE.md
+# "No such file" → BLOCKED. Run `peaks standards init --project <repo> --apply --json`
+# (first time) or `peaks standards update --project <repo> --apply --json` (existing).
+ls <repo>/.claude/rules/common/coding-style.md \
+   <repo>/.claude/rules/common/code-review.md \
+   <repo>/.claude/rules/common/security.md
+# Any "No such file" → BLOCKED. The standards apply step did not complete; re-run
+# standards init/update with --apply and re-verify.
+# Skipping Gate G (e.g. because the user did not explicitly authorize writes) is
+# only acceptable in `assisted`/`strict` modes where the user actively declined; in
+# `full-auto`/`swarm` the absence of these files is a workflow violation.
+```
+
 
 ## Swarm parallel phase
 
@@ -558,9 +578,17 @@ peaks scan archetype --project <repo> --json
 peaks scan existing-system --project <repo> --json
 # → copy tokens, sources, conventions, inconsistencies into .peaks/<session-id>/system/existing-system.md (Gate A.5)
 
-# 1. Standards preflight
-peaks standards init --project <repo> --dry-run --json
+# 1. Standards preflight + apply
+#    Run dry-run first to inspect deltas, then APPLY. In full-auto and swarm modes,
+#    --apply is the default — Standards files (CLAUDE.md, .claude/rules/**) live INSIDE
+#    the target project and are required for downstream skill preflight, so producing
+#    them is part of completing the workflow. Assisted/Strict modes pause for [CONFIRM]
+#    between dry-run and apply.
+peaks standards init   --project <repo> --dry-run --json
 # or: peaks standards update --project <repo> --dry-run --json
+peaks standards init   --project <repo> --apply --json
+# or: peaks standards update --project <repo> --apply --json
+# After apply, verify the files actually exist on disk (see Gate G).
 
 # 2. PRD (Assisted/Strict: [CONFIRM] before confirmed-by-user)
 # Classify the request type from the PRD: feature | bugfix | refactor | docs | config | chore
@@ -648,7 +676,7 @@ Before orchestrating an end-to-end code repository workflow, gather the project
 - `peaks standards init --project <path> --dry-run`
 - `peaks standards update --project <path> --dry-run`
 
-Use `standards init` for first-time creation and `standards update` for existing `CLAUDE.md` append/review behavior. Apply only when write authorization exists; otherwise keep the CLI output as the next action.
+Use `standards init` for first-time creation and `standards update` for existing `CLAUDE.md` append/review behavior. In `full-auto` and `swarm` profiles, `--apply` runs automatically after `--dry-run` succeeds — these files live inside the target project, are required for downstream skill preflight, and producing them is part of finishing the workflow (Gate G enforces this). `assisted` and `strict` profiles pause for explicit user confirmation between dry-run and apply.
 
 **CRITICAL — Standards must reflect the project scan.** When generating or updating `CLAUDE.md`, the content must reference concrete findings from `.peaks/<id>/rd/project-scan.md`: the detected component library (e.g. "This project uses antd 5.x"), CSS solution (e.g. "Uses Less via Umi"), build tool, state management, and routing. Never emit a generic template that says "read .claude/rules/..." without naming the actual project stack. If the project-scan has not been run yet, run it before standards init/update.
 
@@ -703,7 +731,13 @@ Use Peaks TXT for the compact handoff capsule: mode, validated decisions, artifa
 
 **Codegraph**: Optional project-analysis before RD handoff. Use `peaks codegraph affected --project <path> <changed-files...> --json` for regression-surface hints. Output as untrusted supporting evidence only; never commit `.codegraph/` artifacts.
 
-**External skills**: All external skill references (`mattpocock/skills`, `awesome-design-md`, `taste-skill`, `shadcn/ui`, `Chrome DevTools MCP`, `Figma Context MCP`, `Context7`, etc.) follow the three-stage pattern: capability discovery before naming, reference-only (no execute/install/persist), Peaks CLI for all side effects. External skills inform, they do not approve.
+## Codegraph orchestration context
+
+Solo treats `peaks codegraph affected --project <path> <changed-files...> --json` as an optional project-analysis enhancement that informs the role handoff between PRD, RD, and QA. The output is untrusted supporting evidence — Solo must not treat codegraph output as approval for scope, design, or QA verdict.
+
+Do not run upstream installer flows, mutate agent settings, or commit `.codegraph/` artifacts into git. Peaks gates remain authoritative; codegraph context is a hint, never a substitute for role-skill output.
+
+**External skills**: All external skill references (`mattpocock/skills`, `awesome-design-md`, `taste-skill`, `shadcn/ui`, `Chrome DevTools MCP`, `Figma Context MCP`, `Context7`, etc.) follow the three-stage pattern: capability discovery via `peaks capabilities` before naming, references only (no execute/install/persist), Peaks CLI for all side effects. Do not execute upstream installers, do not install upstream resources, do not persist sensitive examples — Peaks gates remain authoritative. External skills inform, they do not approve.
 
 **OpenSpec lifecycle**: `render → validate → show → to-rd → validate → archive`. Solo's default runbook handles the exit gate (validate → archive after QA pass). Entry-gate validation (to-rd before slicing) is available when `openspec/` exists pre-workflow; Solo delegates it to `peaks-rd` during implementation.
 

package/skills/peaks-ui/SKILL.md

@@ -34,8 +34,8 @@ Every UI invocation that touches user-visible behavior — including bug fixes t
 
 | # | File | Purpose |
 |---|------|---------|
-| 1 | `.peaks/<id>/ui/design-draft.md` | Design direction, dials, component specs, anti-template checklist |
-| 2 | `.peaks/<id>/ui/requests/<rid>.md` | Links to #1, records visual direction decisions, regression seeds |
+| 1 | `.peaks/<session-id>/ui/design-draft.md` | Design direction, dials, component specs, anti-template checklist |
+| 2 | `.peaks/<session-id>/ui/requests/<request-id>.md` | Links to #1, records visual direction decisions, regression seeds |
 
 RD consumes the design-draft to implement; QA consumes it for visual regression checks.
 
@@ -124,6 +124,14 @@ You cannot declare a phase complete from memory. Each gate below is a `ls` comma
 ls .peaks/<id>/ui/design-draft.md
 # Expected output: .peaks/<id>/ui/design-draft.md
 # "No such file" → STOP, write the design-draft first. Do not proceed to handoff.
+
+# Gate A also requires an ASCII wireframe section with at least one fenced block.
+grep -c "^## Layout (ASCII wireframe)" .peaks/<id>/ui/design-draft.md
+# Expected: >= 1. Zero → BLOCKED. The mandatory ASCII wireframe section is missing.
+grep -c '^```' .peaks/<id>/ui/design-draft.md
+# Expected: >= 2 (one or more fenced code blocks for ASCII wireframes).
+# Zero → BLOCKED. Prose-only layout description is not acceptable; add ASCII wireframes
+# for the main page and every meaningful modal/drawer/state.
 ```
 
 **Gate B — Before handoff to RD:**
@@ -238,7 +246,7 @@ Every UI invocation that touches user-visible behavior MUST produce a design-dra
 1. **Component library** — detected library name, version, design-system packages (e.g. `antd 5.x` + `@ant-design/pro-components`). Verify by checking `package.json` and source imports — never assume.
 2. **Style direction** — named visual direction (editorial, bento, Swiss, glass, luxury, product-system, etc.) with 1-2 sentence rationale
 3. **Design dials** — variance (conservative/moderate/bold), motion intensity (minimal/medium/rich), visual density (sparse/comfortable/dense), typography pair (heading + body), palette (primary, surface, text, accent tokens)
-4. **Page/component structure** — layout sketch (ASCII wireframe or description), component tree (which library components used where), hierarchy (primary/secondary/tertiary content zones)
+4. **Page/component structure** — MANDATORY ASCII wireframe (not prose description) under a dedicated `## Layout (ASCII wireframe)` section, component tree (which library components used where), hierarchy (primary/secondary/tertiary content zones). Every meaningful surface (main page, each modal/drawer, key state) must have its own fenced ASCII block. Prose-only layout descriptions do NOT satisfy this section and Gate A will reject the design-draft.
 5. **Component specifications** — for each new or modified component: which library component it uses, which props/tokens customize it, states (loading, empty, error, hover, focus, active, disabled), responsive behavior
 6. **CSS framework rules** — which CSS approach to use (component-library tokens, CSS Modules, TailwindCSS utilities if already present), explicit prohibition against mixing conflicting frameworks
 7. **States and edge cases** — loading skeleton, empty state, error state, edge-case handling for each user-visible surface