peaks-cli 1.0.11 → 1.0.13

package/dist/src/services/openspec/openspec-scan-service.js

@@ -0,0 +1,123 @@
+import { join } from 'node:path';
+import { isDirectory, listDirectories, pathExists, readText } from '../../shared/fs.js';
+function defaultOpenSpecRoot() {
+    return join(process.cwd(), 'openspec');
+}
+function parseMarkdownSections(markdown) {
+    const sections = new Map();
+    const lines = markdown.split(/\r?\n/);
+    let currentHeading = null;
+    let buffer = [];
+    const flush = () => {
+        if (currentHeading !== null) {
+            sections.set(currentHeading, buffer.join('\n').trim());
+        }
+    };
+    for (const line of lines) {
+        if (line.startsWith('## ')) {
+            flush();
+            currentHeading = line.slice(3).trim();
+            buffer = [];
+        }
+        else if (currentHeading !== null) {
+            buffer.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+function parseBullets(content) {
+    return content
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('- ') || line === '-')
+        .map((line) => line.replace(/^-\s*/, '').trim())
+        .filter((line) => line.length > 0 && !line.startsWith('[ ]') && !line.startsWith('[x]') && !line.startsWith('[X]'));
+}
+function parseProposal(markdown) {
+    const sections = parseMarkdownSections(markdown);
+    const why = sections.get('Why') ?? '';
+    return {
+        why,
+        whatChanges: parseBullets(sections.get('What Changes') ?? ''),
+        outOfScope: parseBullets(sections.get('Out of Scope') ?? ''),
+        dependencies: parseBullets(sections.get('Dependencies') ?? ''),
+        risks: parseBullets(sections.get('Risks') ?? ''),
+        acceptanceCriteria: parseBullets(sections.get('Acceptance Criteria') ?? '')
+    };
+}
+function parseTaskProgress(markdown) {
+    const sections = parseMarkdownSections(markdown);
+    const sectionEntries = [];
+    let totalTodo = 0;
+    let doneTodo = 0;
+    for (const [heading, body] of sections.entries()) {
+        let sectionTotal = 0;
+        let sectionDone = 0;
+        for (const line of body.split(/\r?\n/)) {
+            const trimmed = line.trim();
+            if (/^- \[[ xX]\]/.test(trimmed)) {
+                sectionTotal += 1;
+                if (/^- \[[xX]\]/.test(trimmed)) {
+                    sectionDone += 1;
+                }
+            }
+        }
+        if (sectionTotal > 0) {
+            sectionEntries.push({ heading, total: sectionTotal, done: sectionDone });
+            totalTodo += sectionTotal;
+            doneTodo += sectionDone;
+        }
+    }
+    return { totalTodo, doneTodo, sections: sectionEntries };
+}
+async function listSpecs(changeRoot) {
+    const specsRoot = join(changeRoot, 'specs');
+    if (!(await isDirectory(specsRoot))) {
+        return [];
+    }
+    return listDirectories(specsRoot);
+}
+async function resolvePaths(changeRoot) {
+    const proposalPath = join(changeRoot, 'proposal.md');
+    const tasksPath = join(changeRoot, 'tasks.md');
+    const designPath = join(changeRoot, 'design.md');
+    return {
+        root: changeRoot,
+        proposal: (await pathExists(proposalPath)) ? proposalPath : null,
+        tasks: (await pathExists(tasksPath)) ? tasksPath : null,
+        design: (await pathExists(designPath)) ? designPath : null
+    };
+}
+async function buildSummary(id, changeRoot) {
+    const paths = await resolvePaths(changeRoot);
+    const specs = await listSpecs(changeRoot);
+    let taskProgress = null;
+    if (paths.tasks !== null) {
+        taskProgress = parseTaskProgress(await readText(paths.tasks));
+    }
+    return { id, paths, specs, taskProgress };
+}
+export async function scanOpenSpec(options = {}) {
+    const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
+    const changesRoot = join(openspecRoot, 'changes');
+    if (!(await isDirectory(openspecRoot))) {
+        return { openspecRoot, changesRoot, exists: false, changes: [] };
+    }
+    if (!(await isDirectory(changesRoot))) {
+        return { openspecRoot, changesRoot, exists: true, changes: [] };
+    }
+    const ids = await listDirectories(changesRoot);
+    const changes = await Promise.all(ids.map((id) => buildSummary(id, join(changesRoot, id))));
+    return { openspecRoot, changesRoot, exists: true, changes };
+}
+export async function loadOpenSpecChange(changeId, options = {}) {
+    const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
+    const changeRoot = join(openspecRoot, 'changes', changeId);
+    if (!(await isDirectory(changeRoot))) {
+        return null;
+    }
+    const summary = await buildSummary(changeId, changeRoot);
+    const proposal = summary.paths.proposal === null ? null : parseProposal(await readText(summary.paths.proposal));
+    return { ...summary, proposal };
+}

package/dist/src/services/openspec/openspec-types.d.ts

@@ -0,0 +1,39 @@
+export type OpenSpecProposal = {
+    why: string;
+    whatChanges: string[];
+    outOfScope: string[];
+    dependencies: string[];
+    risks: string[];
+    acceptanceCriteria: string[];
+};
+export type OpenSpecTaskSection = {
+    heading: string;
+    total: number;
+    done: number;
+};
+export type OpenSpecTaskProgress = {
+    totalTodo: number;
+    doneTodo: number;
+    sections: OpenSpecTaskSection[];
+};
+export type OpenSpecChangePaths = {
+    root: string;
+    proposal: string | null;
+    tasks: string | null;
+    design: string | null;
+};
+export type OpenSpecChangeSummary = {
+    id: string;
+    paths: OpenSpecChangePaths;
+    specs: string[];
+    taskProgress: OpenSpecTaskProgress | null;
+};
+export type OpenSpecChangeDetail = OpenSpecChangeSummary & {
+    proposal: OpenSpecProposal | null;
+};
+export type OpenSpecScanReport = {
+    openspecRoot: string;
+    changesRoot: string;
+    exists: boolean;
+    changes: OpenSpecChangeSummary[];
+};

package/dist/src/services/openspec/openspec-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/services/openspec/openspec-validate-service.d.ts

@@ -0,0 +1,27 @@
+import { type OpenSpecScanOptions } from './openspec-scan-service.js';
+export type OpenSpecValidationLevel = 'error' | 'warning';
+export type OpenSpecValidationIssue = {
+    level: OpenSpecValidationLevel;
+    rule: string;
+    message: string;
+};
+export type OpenSpecValidationSource = 'internal' | 'openspec-cli';
+export type OpenSpecValidationResult = {
+    changeId: string;
+    valid: boolean;
+    source: OpenSpecValidationSource;
+    issues: OpenSpecValidationIssue[];
+    cliOutput?: string;
+};
+export type ExternalRunnerOutcome = {
+    available: boolean;
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+};
+export type ExternalRunner = (command: string, args: string[]) => Promise<ExternalRunnerOutcome>;
+export type OpenSpecValidateOptions = OpenSpecScanOptions & {
+    preferExternal?: boolean;
+    externalRunner?: ExternalRunner;
+};
+export declare function validateOpenSpecChange(changeId: string, options?: OpenSpecValidateOptions): Promise<OpenSpecValidationResult | null>;

package/dist/src/services/openspec/openspec-validate-service.js

@@ -0,0 +1,77 @@
+import { join } from 'node:path';
+import { isDirectory } from '../../shared/fs.js';
+import { loadOpenSpecChange } from './openspec-scan-service.js';
+const CHANGE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function defaultOpenSpecRoot() {
+    return join(process.cwd(), 'openspec');
+}
+async function defaultExternalRunner(_command, _args) {
+    return { available: false, exitCode: null, stdout: '', stderr: '' };
+}
+function buildInternalIssues(changeId, detail) {
+    const issues = [];
+    if (!CHANGE_ID_PATTERN.test(changeId)) {
+        issues.push({
+            level: 'error',
+            rule: 'change-id-format',
+            message: `changeId ${changeId} does not match [A-Za-z0-9][A-Za-z0-9._-]*`
+        });
+    }
+    if (detail === null || detail.proposal === null) {
+        issues.push({ level: 'error', rule: 'proposal-exists', message: 'proposal.md is missing' });
+        return issues;
+    }
+    const proposal = detail.proposal;
+    if (proposal.why.length === 0) {
+        issues.push({ level: 'warning', rule: 'why-non-empty', message: 'Why section is empty' });
+    }
+    if (proposal.whatChanges.length === 0) {
+        issues.push({ level: 'error', rule: 'what-changes-non-empty', message: 'What Changes section has no bullets' });
+    }
+    if (proposal.acceptanceCriteria.length === 0) {
+        issues.push({ level: 'error', rule: 'acceptance-non-empty', message: 'Acceptance Criteria section has no bullets' });
+    }
+    return issues;
+}
+function hasErrors(issues) {
+    return issues.some((issue) => issue.level === 'error');
+}
+async function runInternal(changeId, openspecRoot) {
+    const changeRoot = join(openspecRoot, 'changes', changeId);
+    if (!(await isDirectory(changeRoot))) {
+        return null;
+    }
+    const detail = await loadOpenSpecChange(changeId, { openspecRoot });
+    const issues = buildInternalIssues(changeId, detail);
+    return {
+        changeId,
+        valid: !hasErrors(issues),
+        source: 'internal',
+        issues
+    };
+}
+export async function validateOpenSpecChange(changeId, options = {}) {
+    const openspecRoot = options.openspecRoot ?? defaultOpenSpecRoot();
+    const runner = options.externalRunner ?? defaultExternalRunner;
+    if (options.preferExternal === true) {
+        const outcome = await runner('openspec', ['validate', changeId]);
+        if (outcome.available) {
+            const cliOutput = [outcome.stdout, outcome.stderr].filter((part) => part.length > 0).join('\n').trim();
+            const passed = outcome.exitCode === 0;
+            const issues = passed
+                ? []
+                : [{ level: 'error', rule: 'openspec-cli-failed', message: `openspec validate exited with code ${outcome.exitCode ?? 'null'}` }];
+            return { changeId, valid: passed, source: 'openspec-cli', issues, cliOutput };
+        }
+        const internal = await runInternal(changeId, openspecRoot);
+        if (internal === null) {
+            return null;
+        }
+        internal.issues = [
+            { level: 'warning', rule: 'openspec-cli-unavailable', message: 'openspec CLI not found, fell back to internal lint' },
+            ...internal.issues
+        ];
+        return internal;
+    }
+    return runInternal(changeId, openspecRoot);
+}

package/dist/src/services/recommendations/capability-seed-items.js

@@ -100,6 +100,7 @@ export const seedCapabilityItems = [
     capability('gitnexus.repo-intelligence', 'gitnexus', 'GitNexus Repository Intelligence', 'cli', 'repo-intelligence', ['engineer'], 'medium', 'local-repo-scan', 'Use local project scanning through Peaks RD.', 'Repository Intelligence', '仓库智能分析', 'Repository intelligence should be proxied through Peaks before use.', '仓库智能分析应先通过 Peaks 代理边界再使用。'),
     capability('claude-code-best-practice.workflow-guidance', 'claude-code-best-practice', 'Claude Code Best Practice', 'doc', 'workflow-guidance', ['engineer'], 'low', 'peaks-built-in-rules', 'Use Peaks built-in workflow and review rules.', 'Claude Code Best Practice', 'Claude Code 最佳实践', 'Guidance for Claude Code engineering workflows.', 'Claude Code 工程工作流指导。'),
     capability('superpowers.workflow-methodology', 'superpowers', 'Superpowers Methodology', 'workflow', 'workflow-methodology', ['product', 'engineer'], 'low', 'peaks-workflow-route', 'Use Peaks route/autonomous plans.', 'Superpowers Methodology', 'Superpowers 方法论', 'Workflow and artifact methodology reference.', '工作流与 artifact 方法论参考。'),
+    capability('understand-anything.knowledge-graph', 'understand-anything', 'Understand Anything Knowledge Graph', 'skill', 'project-analysis', ['engineer', 'product', 'qa'], 'low', 'peaks-codegraph-or-rd-scan', 'Use peaks codegraph or peaks RD project scan when Understand Anything is not installed. Optionally suggest installing it via Claude Code: /plugin marketplace add Lum1104/Understand-Anything then /plugin install understand-anything.', 'Understand Anything Knowledge Graph', 'Understand Anything 知识图谱', 'Multi-agent project knowledge graph that Peaks reads from .understand-anything/knowledge-graph.json when it has been generated by the Understand Anything plugin in Claude Code.', '通过 Claude Code 的 Understand Anything 插件生成的多 agent 知识图谱，Peaks 在 .understand-anything/knowledge-graph.json 存在时读取它作为项目分析证据。'),
     capability('penpot.design-source', 'penpot', 'Penpot Design Source', 'doc', 'design-source', ['designer', 'engineer'], 'medium', 'manual-design-input', 'Ask for exported design notes or screenshots.', 'Penpot Design Source', 'Penpot 设计来源', 'Design-source reference for UI planning.', '用于 UI 规划的设计来源参考。'),
     capability('gstack.product-stack-guidance', 'gstack', 'Product Stack Guidance', 'doc', 'product-guidance', ['product'], 'low', 'peaks-prd', 'Use peaks-prd for product goals and non-goals.', 'Product Stack Guidance', '产品栈指导', 'Product and startup stack guidance reference.', '产品与创业栈指导参考。'),
     capability('awesome-design-md.design-reference', 'awesome-design-md', 'Design Markdown Reference', 'doc', 'design-reference', ['designer', 'engineer'], 'low', 'peaks-ui-visual-direction', 'Use peaks-ui to define visual direction and interaction constraints.', 'Design Reference', '设计参考', 'Design markdown examples and inspiration.', '设计 markdown 示例与灵感。'),

package/dist/src/services/skills/skill-runbook-service.d.ts

@@ -0,0 +1,11 @@
+export type SkillRunbookInspection = {
+    name: string;
+    directory: string;
+    hasRunbook: boolean;
+    peaksCommandCount: number;
+    peaksCommandLines: string[];
+    destructiveApplyLines: string[];
+    hasAuthorizationNote: boolean;
+    ok: boolean;
+};
+export declare function inspectSkillRunbook(name: string, baseDir?: string): Promise<SkillRunbookInspection>;

package/dist/src/services/skills/skill-runbook-service.js

@@ -0,0 +1,60 @@
+import { readText } from '../../shared/fs.js';
+import { loadSkillRegistry } from './skill-registry.js';
+const DESTRUCTIVE_APPLY_PATTERNS = [
+    /peaks\s+memory\s+sync[^\n]*--apply/,
+    /peaks\s+memory\s+extract[^\n]*--apply/,
+    /peaks\s+artifacts\s+sync[^\n]*--apply/,
+    /peaks\s+openspec\s+archive[^\n]*--apply/,
+    /peaks\s+standards\s+(?:init|update)[^\n]*--apply/
+];
+const AUTHORIZATION_KEYWORDS_PATTERN = /authoriz|explicit|--dry-run|approv|only after|only when/i;
+const PEAKS_COMMAND_LINE_PATTERN = /^\s*peaks\s+\w/;
+function extractRunbookSection(body) {
+    const match = /## Default runbook\n+([\s\S]*?)(?=\n## |$)/.exec(body);
+    return match === null ? null : (match[1] ?? null);
+}
+function findDestructiveApplyLines(section) {
+    const lines = section.split(/\r?\n/);
+    return lines.filter((line) => DESTRUCTIVE_APPLY_PATTERNS.some((pattern) => pattern.test(line)));
+}
+function findPeaksCommandLines(section) {
+    return section
+        .split(/\r?\n/)
+        .filter((line) => PEAKS_COMMAND_LINE_PATTERN.test(line))
+        .map((line) => line.trim());
+}
+export async function inspectSkillRunbook(name, baseDir) {
+    const registry = await loadSkillRegistry(baseDir);
+    const skill = registry.skills.find((entry) => entry.name === name);
+    if (skill === undefined) {
+        throw new Error(`Skill "${name}" not found under skills directory`);
+    }
+    const body = await readText(skill.skillPath);
+    const section = extractRunbookSection(body);
+    if (section === null) {
+        return {
+            name: skill.name,
+            directory: skill.directory,
+            hasRunbook: false,
+            peaksCommandCount: 0,
+            peaksCommandLines: [],
+            destructiveApplyLines: [],
+            hasAuthorizationNote: false,
+            ok: false
+        };
+    }
+    const peaksCommandLines = findPeaksCommandLines(section);
+    const destructiveApplyLines = findDestructiveApplyLines(section);
+    const hasAuthorizationNote = AUTHORIZATION_KEYWORDS_PATTERN.test(section);
+    const ok = destructiveApplyLines.length === 0 || hasAuthorizationNote;
+    return {
+        name: skill.name,
+        directory: skill.directory,
+        hasRunbook: true,
+        peaksCommandCount: peaksCommandLines.length,
+        peaksCommandLines,
+        destructiveApplyLines,
+        hasAuthorizationNote,
+        ok
+    };
+}

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

@@ -96,20 +96,17 @@ function renderClaudeMd(language) {
         '- peaks-solo summarizes RD and QA standards preflight before end-to-end code workflows.',
         '',
         'Rules:',
-        '- RED LINE: Read `.claude/rules/common/coding-style.md` before editing code, and treat its file-size limits as blockers.',
-        '- RED LINE: Strictly prohibit oversized single files; split large files into cohesive modules before handoff.',
+        '- 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 references: https://github.com/affaan-m/everything-claude-code and https://github.com/SquabbyZ/andrej-karpathy-skills are used as curated references only. Treat andrej-karpathy-skills code quality guidance as a red line during peaks-rd implementation. Do not execute or install external content without explicit approval.',
+        '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')}- RED LINE: Strictly prohibit oversized single files; split large files into cohesive modules before handoff.
-- RED LINE: Treat https://github.com/SquabbyZ/andrej-karpathy-skills code quality guidance as a blocker for peaks-rd implementation.
-- Prefer simple, readable code over clever abstractions.
+    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.
@@ -117,9 +114,7 @@ function renderCommonCodingStyle() {
 `;
 }
 function renderCodeReview() {
-    return `${renderHeader('Code Review Standards')}- RED LINE: Block oversized single-file changes and require cohesive module splits before approval.
-- RED LINE: Treat https://github.com/SquabbyZ/andrej-karpathy-skills code quality guidance as a blocker during review.
-- Review diffs for correctness, maintainability, test coverage, and regression risk.
+    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.

package/dist/src/services/understand/understand-scan-service.d.ts

@@ -0,0 +1,28 @@
+import type { UnderstandScanReport } from './understand-types.js';
+export type UnderstandScanOptions = {
+    projectRoot: string;
+    artifactDir?: string;
+};
+export declare function scanUnderstandAnything(options: UnderstandScanOptions): Promise<UnderstandScanReport>;
+export type UnderstandGraphSummary = {
+    exists: boolean;
+    path: string;
+    generatedAt: string | null;
+    topLevelFields: string[];
+    counts: {
+        nodes: number;
+        edges: number;
+        layers: number;
+        tours: number;
+    };
+    layerNames: string[];
+    tourNames: string[];
+    sampleNodes: string[];
+    parseError?: string;
+};
+export type SummarizeKnowledgeGraphOptions = {
+    projectRoot: string;
+    artifactDir?: string;
+    sampleSize?: number;
+};
+export declare function summarizeKnowledgeGraph(options: SummarizeKnowledgeGraphOptions): Promise<UnderstandGraphSummary>;

package/dist/src/services/understand/understand-scan-service.js

@@ -0,0 +1,157 @@
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDirectory, pathExists, readText } from '../../shared/fs.js';
+import { getErrorMessage } from '../../shared/result.js';
+function defaultArtifactDir(projectRoot) {
+    return join(projectRoot, '.understand-anything');
+}
+function countArrayField(record, key) {
+    const value = record[key];
+    return Array.isArray(value) ? value.length : 0;
+}
+async function readFlag(path) {
+    return { exists: await pathExists(path), path };
+}
+async function readGraph(graphPath) {
+    if (!(await pathExists(graphPath))) {
+        return { exists: false, path: graphPath };
+    }
+    const stats = await stat(graphPath);
+    const raw = await readText(graphPath);
+    try {
+        const parsed = JSON.parse(raw);
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {
+                exists: true,
+                path: graphPath,
+                sizeBytes: stats.size,
+                parseError: 'knowledge-graph.json must be a JSON object'
+            };
+        }
+        const record = parsed;
+        return {
+            exists: true,
+            path: graphPath,
+            sizeBytes: stats.size,
+            topLevelFields: Object.keys(record).sort(),
+            counts: {
+                nodes: countArrayField(record, 'nodes'),
+                edges: countArrayField(record, 'edges'),
+                layers: countArrayField(record, 'layers'),
+                tours: countArrayField(record, 'tours')
+            }
+        };
+    }
+    catch (error) {
+        return {
+            exists: true,
+            path: graphPath,
+            sizeBytes: stats.size,
+            parseError: getErrorMessage(error)
+        };
+    }
+}
+export async function scanUnderstandAnything(options) {
+    const artifactDir = options.artifactDir ?? defaultArtifactDir(options.projectRoot);
+    const exists = await isDirectory(artifactDir);
+    if (!exists) {
+        return {
+            exists: false,
+            artifactDir,
+            graph: { exists: false, path: join(artifactDir, 'knowledge-graph.json') },
+            intermediate: { exists: false, path: join(artifactDir, 'intermediate') },
+            diffOverlay: { exists: false, path: join(artifactDir, 'diff-overlay.json') }
+        };
+    }
+    const graph = await readGraph(join(artifactDir, 'knowledge-graph.json'));
+    const intermediate = await readFlag(join(artifactDir, 'intermediate'));
+    const diffOverlay = await readFlag(join(artifactDir, 'diff-overlay.json'));
+    return { exists: true, artifactDir, graph, intermediate, diffOverlay };
+}
+function pickStringId(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    for (const key of ['id', 'path', 'name', 'label']) {
+        const candidate = record[key];
+        if (typeof candidate === 'string' && candidate.length > 0) {
+            return candidate;
+        }
+    }
+    return null;
+}
+function pickStringField(record, key) {
+    const value = record[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function pickNameArray(record, key) {
+    const value = record[key];
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((entry) => {
+        if (typeof entry === 'string') {
+            return entry;
+        }
+        return pickStringId(entry);
+    })
+        .filter((entry) => entry !== null);
+}
+export async function summarizeKnowledgeGraph(options) {
+    const scanOptions = { projectRoot: options.projectRoot };
+    if (options.artifactDir !== undefined) {
+        scanOptions.artifactDir = options.artifactDir;
+    }
+    const scan = await scanUnderstandAnything(scanOptions);
+    const sampleSize = options.sampleSize ?? 5;
+    if (!scan.graph.exists) {
+        return {
+            exists: false,
+            path: scan.graph.path,
+            generatedAt: null,
+            topLevelFields: [],
+            counts: { nodes: 0, edges: 0, layers: 0, tours: 0 },
+            layerNames: [],
+            tourNames: [],
+            sampleNodes: []
+        };
+    }
+    if (scan.graph.parseError !== undefined) {
+        return {
+            exists: true,
+            path: scan.graph.path,
+            generatedAt: null,
+            topLevelFields: [],
+            counts: { nodes: 0, edges: 0, layers: 0, tours: 0 },
+            layerNames: [],
+            tourNames: [],
+            sampleNodes: [],
+            parseError: scan.graph.parseError
+        };
+    }
+    const raw = await readText(scan.graph.path);
+    const parsed = JSON.parse(raw);
+    const record = parsed;
+    const generatedAt = pickStringField(record, 'generatedAt');
+    const nodes = Array.isArray(record.nodes) ? record.nodes : [];
+    const sampleNodes = nodes.slice(0, sampleSize)
+        .map((entry) => pickStringId(entry))
+        .filter((entry) => entry !== null);
+    return {
+        exists: true,
+        path: scan.graph.path,
+        generatedAt,
+        topLevelFields: Object.keys(record).sort(),
+        counts: {
+            nodes: countArrayField(record, 'nodes'),
+            edges: countArrayField(record, 'edges'),
+            layers: countArrayField(record, 'layers'),
+            tours: countArrayField(record, 'tours')
+        },
+        layerNames: pickNameArray(record, 'layers'),
+        tourNames: pickNameArray(record, 'tours'),
+        sampleNodes
+    };
+}

package/dist/src/services/understand/understand-types.d.ts

@@ -0,0 +1,24 @@
+export type UnderstandGraphReport = {
+    exists: boolean;
+    path: string;
+    sizeBytes?: number;
+    topLevelFields?: string[];
+    counts?: {
+        nodes: number;
+        edges: number;
+        layers: number;
+        tours: number;
+    };
+    parseError?: string;
+};
+export type UnderstandFlagReport = {
+    exists: boolean;
+    path: string;
+};
+export type UnderstandScanReport = {
+    exists: boolean;
+    artifactDir: string;
+    graph: UnderstandGraphReport;
+    intermediate: UnderstandFlagReport;
+    diffOverlay: UnderstandFlagReport;
+};

package/dist/src/services/understand/understand-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/shared/json-schema-mini.d.ts

@@ -0,0 +1,10 @@
+export type JsonSchemaIssue = {
+    path: string;
+    message: string;
+};
+export type JsonSchemaResult = {
+    valid: boolean;
+    errors: JsonSchemaIssue[];
+};
+export type JsonSchemaNode = Record<string, unknown>;
+export declare function validateAgainstSchema(value: unknown, schema: JsonSchemaNode): JsonSchemaResult;