peaks-cli 1.0.0

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

@@ -0,0 +1,383 @@
+import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, realpathSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+const SOURCE = {
+    sourceId: 'everything-claude-code',
+    url: 'https://github.com/affaan-m/everything-claude-code',
+    usage: 'curated-baseline-reference'
+};
+const SKILL_PREFLIGHT = {
+    appliesTo: ['peaks-rd', 'peaks-qa', 'peaks-solo'],
+    summary: 'peaks-rd、peaks-qa、peaks-solo 进入代码仓工作流时自动 preflight 项目规范。'
+};
+const SUPPORTED_LANGUAGES = new Set(['generic', 'typescript', 'javascript', 'python', 'go', 'rust']);
+function normalizeRoot(path) {
+    return realpathSync(resolve(path));
+}
+function isInsidePath(childPath, parentPath) {
+    const rel = relative(parentPath, childPath);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+function assertDirectoryNotSymlink(path) {
+    if (existsSync(path) && lstatSync(path).isSymbolicLink()) {
+        throw new Error('Project standards directory must stay inside the project root');
+    }
+}
+function assertRealPathInsideProject(path, projectRoot) {
+    if (!isInsidePath(realpathSync(path), projectRoot)) {
+        throw new Error('Project standards write target must stay inside the project root');
+    }
+}
+function 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 detectLanguage(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';
+}
+function renderHeader(title) {
+    return [
+        `# ${title}`,
+        '',
+        'Source: Peaks curated baseline; everything-claude-code reference: https://github.com/affaan-m/everything-claude-code',
+        'Scope: project-local standards for peaks-rd, peaks-qa, and peaks-solo workflow preflight.',
+        ''
+    ].join('\n');
+}
+function renderClaudeMd(language) {
+    return [
+        '# Project Instructions',
+        '',
+        '> 🤖 AI 生成，请审阅',
+        '',
+        'This repository uses project-local Peaks standards. Existing repository conventions override generic generated guidance.',
+        '',
+        'Peaks workflow automation:',
+        '- peaks-rd checks these standards before RD planning or implementation work.',
+        '- peaks-qa checks code review and security guidance before verification work.',
+        '- peaks-solo summarizes RD and QA standards preflight before end-to-end code workflows.',
+        '',
+        'Rules:',
+        '- Read `.claude/rules/common/coding-style.md` before editing code.',
+        '- Read `.claude/rules/common/code-review.md` before reviewing changes.',
+        '- Read `.claude/rules/common/security.md` before touching filesystem, user input, external calls, auth, or secrets.',
+        `- Read .claude/rules/${language}/coding-style.md for language-specific standards when applicable.`,
+        '',
+        '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');
+}
+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) {
+    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.
+`;
+}
+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 writeMissingStandardsRules(plan) {
+    const writtenFiles = [];
+    for (const write of plan.plannedWrites) {
+        if (write.relativePath === 'CLAUDE.md' || write.status === 'existing')
+            continue;
+        const targetPath = resolve(write.filePath);
+        const targetDir = dirname(targetPath);
+        mkdirSync(targetDir, { recursive: true });
+        assertRealPathInsideProject(targetDir, plan.projectRoot);
+        writeNewFile(targetPath, write.content);
+        writtenFiles.push(write.relativePath);
+    }
+    return writtenFiles;
+}
+function createTemplates(language) {
+    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) }
+    ];
+}
+function createManagedClaudeBlock(language) {
+    return renderManagedClaudeMdIndex(language);
+}
+function buildClaudeUpdate(projectRoot, language) {
+    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).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 ? detectLanguage(projectRoot) : parseLanguage(options.language);
+    const plannedWrites = createTemplates(language).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 claudeMd = buildClaudeUpdate(basePlan.projectRoot, basePlan.language);
+    return {
+        ...basePlan,
+        claudeMd
+    };
+}
+export function executeProjectStandardsInit(options) {
+    const plan = createProjectStandardsInitPlan(options);
+    const writtenFiles = [];
+    if (plan.apply) {
+        assertSafeStandardsRoot(plan.projectRoot);
+        for (const write of plan.plannedWrites) {
+            if (write.status === 'existing')
+                continue;
+            const targetPath = resolve(write.filePath);
+            const targetDir = dirname(targetPath);
+            mkdirSync(targetDir, { recursive: true });
+            assertRealPathInsideProject(targetDir, plan.projectRoot);
+            if (write.relativePath === 'CLAUDE.md') {
+                assertSafeClaudeMdPath(targetPath, plan.projectRoot);
+            }
+            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 };
+    if (plan.apply) {
+        assertSafeStandardsRoot(plan.projectRoot);
+        writtenFiles.push(...writeMissingStandardsRules(plan));
+        const targetPath = resolve(claudeMd.filePath);
+        const targetDir = dirname(targetPath);
+        mkdirSync(targetDir, { recursive: true });
+        assertRealPathInsideProject(targetDir, plan.projectRoot);
+        assertSafeClaudeMdPath(targetPath, plan.projectRoot);
+        if (claudeMd.status === 'planned') {
+            writeNewFile(targetPath, claudeMd.content);
+            writtenFiles.push(claudeMd.relativePath);
+            claudeMd = { ...claudeMd, status: 'written' };
+        }
+        else if (claudeMd.status === 'appended') {
+            appendExistingFile(targetPath, claudeMd.appendBlock);
+            appendedFiles.push(claudeMd.relativePath);
+        }
+    }
+    const plannedWrites = plan.plannedWrites.map((write) => {
+        if (write.relativePath === 'CLAUDE.md') {
+            return { ...write, status: claudeMd.status };
+        }
+        if (writtenFiles.includes(write.relativePath)) {
+            return { ...write, status: 'written' };
+        }
+        return write;
+    });
+    return {
+        ...plan,
+        claudeMd,
+        plannedWrites,
+        writtenFiles,
+        appendedFiles,
+        reviewSuggestions
+    };
+}
+export function summarizeProjectStandardsInitResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        language: result.language,
+        source: result.source,
+        skillPreflight: result.skillPreflight,
+        plannedWrites: result.plannedWrites.map((write) => ({ relativePath: write.relativePath, status: write.status })),
+        writtenFiles: result.writtenFiles,
+        skippedFiles: result.plannedWrites.filter((write) => write.status === 'existing').map((write) => write.relativePath)
+    };
+}
+export function summarizeProjectStandardsUpdateResult(result) {
+    return {
+        apply: result.apply,
+        projectRoot: result.projectRoot,
+        language: result.language,
+        source: result.source,
+        skillPreflight: result.skillPreflight,
+        plannedWrites: result.plannedWrites.map((write) => ({ relativePath: write.relativePath, status: write.status })),
+        writtenFiles: result.writtenFiles,
+        appendedFiles: result.appendedFiles,
+        skippedFiles: result.plannedWrites.filter((write) => write.status === 'existing').map((write) => write.relativePath),
+        reviewSuggestions: result.reviewSuggestions,
+        claudeMd: {
+            relativePath: result.claudeMd.relativePath,
+            status: result.claudeMd.status,
+            reviewSuggestions: result.claudeMd.reviewSuggestions
+        }
+    };
+}

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

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

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

@@ -0,0 +1,236 @@
+import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isInsidePath, stableRealPath } from '../../shared/path-utils.js';
+import { buildArtifactRelativePath, validateChangeIdOrThrow } from '../../shared/change-id.js';
+import { WORKSPACE_UNAVAILABLE_NEXT_ACTIONS } from '../../shared/planner-response.js';
+import { hasValidArtifactWorkspace } from '../artifacts/workspace-service.js';
+export const TECH_REQUIRED_ARTIFACTS = Object.freeze([
+    'frontend-tech-doc.md',
+    'backend-tech-doc.md',
+    'contract-tech-doc.md',
+    'test-tech-doc.md',
+    'platform-tech-doc.md',
+    'security-tech-doc.md',
+    'ci-tech-doc.md',
+    'migration-tech-doc.md',
+    'tech-review-report.md',
+    'tech-approval-record.md',
+]);
+const TECH_WAVE_TASKS = [
+    { name: 'scan', taskIds: ['tech-architecture-scan', 'tech-frontend-scan', 'tech-backend-scan', 'tech-contract-scan', 'tech-test-scan', 'tech-platform-scan', 'tech-security-scan', 'tech-ci-scan'] },
+    { name: 'document', taskIds: ['tech-frontend-doc-worker', 'tech-backend-doc-worker', 'tech-contract-doc-worker', 'tech-test-doc-worker', 'tech-platform-doc-worker', 'tech-security-doc-worker', 'tech-ci-doc-worker', 'tech-migration-doc-worker'] },
+    { name: 'review', taskIds: ['tech-architecture-reviewer', 'tech-contract-reviewer', 'tech-security-reviewer', 'tech-test-reviewer', 'tech-platform-reviewer', 'tech-risk-reviewer'] },
+    { name: 'reducer', taskIds: ['tech-reducer'] },
+];
+function assertNonEmptyGoal(goal) {
+    if (goal.trim().length === 0) {
+        throw new Error('Goal must be non-empty');
+    }
+}
+function architectureRoot(changeId) {
+    return buildArtifactRelativePath(changeId, 'architecture');
+}
+function hasPlannerArtifactWorkspace(artifactWorkspacePath, workspace) {
+    return !!workspace && hasValidArtifactWorkspace(workspace, artifactWorkspacePath);
+}
+function isEscapedArchitectureRoot(rootPath, artifactWorkspacePath) {
+    if (!existsSync(rootPath)) {
+        return false;
+    }
+    try {
+        return !isInsidePath(stableRealPath(rootPath), stableRealPath(artifactWorkspacePath));
+    }
+    catch {
+        return true;
+    }
+}
+function isValidArtifactFile(rootPath, artifact) {
+    const artifactPath = resolve(rootPath, artifact);
+    try {
+        const artifactStat = lstatSync(artifactPath);
+        if (artifactStat.isSymbolicLink())
+            return false;
+        if (!artifactStat.isFile())
+            return false;
+        if (!isInsidePath(stableRealPath(artifactPath), stableRealPath(rootPath)))
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function waveManifestPath(changeId, index, wave) {
+    return buildArtifactRelativePath(changeId, 'architecture', 'waves', `wave-${index + 1}-${wave}.json`);
+}
+function taskPurpose(taskId, goal) {
+    return `${taskId.replace(/^tech-/, '').replace(/-/g, ' ')} for ${goal}`;
+}
+function createTechGraph(request) {
+    validateChangeIdOrThrow(request.changeId);
+    assertNonEmptyGoal(request.goal);
+    const [scanWave, documentWave, reviewWave] = TECH_WAVE_TASKS;
+    const waves = TECH_WAVE_TASKS.map((wave) => ({ name: wave.name, taskIds: [...wave.taskIds] }));
+    const scanTaskIds = scanWave.taskIds;
+    const documentTaskIds = documentWave.taskIds;
+    const reviewTaskIds = reviewWave.taskIds;
+    const tasks = TECH_WAVE_TASKS.flatMap((wave) => wave.taskIds.map((taskId) => {
+        const dependsOn = wave.name === 'scan'
+            ? []
+            : wave.name === 'document'
+                ? [...scanTaskIds]
+                : wave.name === 'review'
+                    ? [...documentTaskIds]
+                    : [...reviewTaskIds];
+        const briefPath = buildArtifactRelativePath(request.changeId, 'architecture', 'workers', taskId, 'brief.md');
+        return {
+            taskId,
+            wave: wave.name,
+            workerKind: taskId,
+            purpose: taskPurpose(taskId, request.goal),
+            inputs: [request.goal, architectureRoot(request.changeId)],
+            outputs: [briefPath],
+            dependsOn,
+            conflictGroup: `tech-${wave.name}`,
+            briefPath,
+        };
+    }));
+    return {
+        changeId: request.changeId,
+        goal: request.goal,
+        swarm: request.swarm,
+        dryRun: true,
+        artifactRoot: architectureRoot(request.changeId),
+        waves,
+        tasks,
+        outputs: {
+            taskGraph: buildArtifactRelativePath(request.changeId, 'architecture', 'tech-task-graph.json'),
+            waveManifests: waves.map((wave, index) => waveManifestPath(request.changeId, index, wave.name)),
+            reviewChecklist: buildArtifactRelativePath(request.changeId, 'architecture', 'tech-review-checklist.md'),
+            approvalTemplate: buildArtifactRelativePath(request.changeId, 'architecture', 'tech-approval-record.template.md'),
+        },
+        blockedReasons: [],
+        nextActions: [],
+    };
+}
+export function createTechPlan(request) {
+    const graph = createTechGraph(request);
+    if (!request.artifactWorkspacePath || !hasPlannerArtifactWorkspace(request.artifactWorkspacePath, request.workspace)) {
+        return {
+            available: false,
+            behavior: 'preview',
+            reason: 'artifact-workspace-unavailable',
+            preview: graph,
+            nextActions: [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS],
+        };
+    }
+    return {
+        available: true,
+        ...graph,
+    };
+}
+export function getTechStatus(options) {
+    validateChangeIdOrThrow(options.changeId);
+    const artifactRoot = architectureRoot(options.changeId);
+    if (!options.artifactWorkspacePath) {
+        return {
+            changeId: options.changeId,
+            status: 'unavailable',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            approvalRecord: null,
+            blockedReasons: ['artifact-workspace-unavailable'],
+            nextActions: [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS],
+        };
+    }
+    if (!hasPlannerArtifactWorkspace(options.artifactWorkspacePath, options.workspace)) {
+        return {
+            changeId: options.changeId,
+            status: 'unavailable',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            approvalRecord: null,
+            blockedReasons: ['artifact-workspace-unavailable'],
+            nextActions: [...WORKSPACE_UNAVAILABLE_NEXT_ACTIONS],
+        };
+    }
+    const rootPath = resolve(options.artifactWorkspacePath, '.peaks', 'changes', options.changeId, 'architecture');
+    const approvalRecord = buildArtifactRelativePath(options.changeId, 'architecture', 'tech-approval-record.md');
+    if (isEscapedArchitectureRoot(rootPath, options.artifactWorkspacePath)) {
+        return {
+            changeId: options.changeId,
+            status: 'blocked',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            approvalRecord: null,
+            blockedReasons: ['tech-artifacts-missing'],
+            nextActions: ['Run peaks tech plan --dry-run, then persist and review the required tech artifacts.'],
+        };
+    }
+    const missingArtifacts = TECH_REQUIRED_ARTIFACTS.filter((artifact) => !existsSync(join(rootPath, artifact)) || !isValidArtifactFile(rootPath, artifact));
+    if (missingArtifacts.length === 1 && missingArtifacts[0] === 'tech-approval-record.md') {
+        return {
+            changeId: options.changeId,
+            status: 'blocked',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts,
+            approvalRecord: null,
+            blockedReasons: ['tech-approval-missing'],
+            nextActions: ['Create tech-approval-record.md with status: approved after review.'],
+        };
+    }
+    if (missingArtifacts.length > 0) {
+        return {
+            changeId: options.changeId,
+            status: missingArtifacts.length === TECH_REQUIRED_ARTIFACTS.length ? 'missing' : 'blocked',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts,
+            approvalRecord: missingArtifacts.includes('tech-approval-record.md') ? null : approvalRecord,
+            blockedReasons: ['tech-artifacts-missing'],
+            nextActions: ['Run peaks tech plan --dry-run, then persist and review the required tech artifacts.'],
+        };
+    }
+    let approvalContent;
+    try {
+        approvalContent = readFileSync(join(rootPath, 'tech-approval-record.md'), 'utf8');
+    }
+    catch {
+        return {
+            changeId: options.changeId,
+            status: 'blocked',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts,
+            approvalRecord,
+            blockedReasons: ['tech-approval-unreadable'],
+            nextActions: ['Ensure tech-approval-record.md is readable and contains status: approved.'],
+        };
+    }
+    if (!approvalContent.split(/\r?\n/).some((line) => line.trim() === 'status: approved')) {
+        return {
+            changeId: options.changeId,
+            status: 'blocked',
+            artifactRoot,
+            requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+            missingArtifacts,
+            approvalRecord,
+            blockedReasons: ['tech-approval-not-approved'],
+            nextActions: ['Update tech-approval-record.md with status: approved after review.'],
+        };
+    }
+    return {
+        changeId: options.changeId,
+        status: 'approved',
+        artifactRoot,
+        requiredArtifacts: [...TECH_REQUIRED_ARTIFACTS],
+        missingArtifacts: [],
+        approvalRecord,
+        blockedReasons: [],
+        nextActions: [],
+    };
+}