@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/core/doctor-commit-evidence.js

@@ -0,0 +1,139 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Read-only persisted commit-evidence diagnostics (TASK-1072 / STORY-526).
+ */
+import { realpathSync } from 'node:fs';
+import { basename, dirname, relative, resolve } from 'node:path';
+import { getConfig } from './config.js';
+import { inspectCommitEvidence, MAX_COMMIT_EVIDENCE_HASHES, } from './doctor-commit-evidence-git.js';
+const NAME = 'Commit Evidence';
+const MAX_REPORTED = 10;
+const LABELS = {
+    normal: 'normal-ref reachable',
+    archive: 'archive-ref reachable',
+    'local-only': 'local-only',
+    unresolvable: 'locally unresolvable',
+    incomplete: 'incomplete',
+};
+function unavailable(reason) {
+    return {
+        name: NAME,
+        status: 'warn',
+        message: `Commit evidence inspection incomplete: ${reason}`,
+        fix: 'Inspect the local repository and configuration, then rerun doctor. No evidence was changed or imported.',
+    };
+}
+/** Shared doctor integration passes only schema-valid live items; archived item files are excluded. */
+export async function detectCommitEvidence(devstepsDir, items) {
+    const hashes = new Set();
+    for (const item of items.values()) {
+        for (const hash of item.commits) {
+            if (typeof hash !== 'string' || !/^[0-9a-f]{40}$/.test(hash)) {
+                return unavailable('A persisted reference is not a canonical full SHA-1; no Git inspection was attempted');
+            }
+            hashes.add(hash);
+            if (hashes.size > MAX_COMMIT_EVIDENCE_HASHES) {
+                return unavailable('More than 10,000 distinct commit references; no Git inspection was attempted');
+            }
+        }
+    }
+    if (hashes.size === 0) {
+        return { name: NAME, status: 'pass', message: 'No persisted commit references to inspect' };
+    }
+    let findings;
+    try {
+        const config = await getConfig(devstepsDir);
+        if (config === null ||
+            typeof config !== 'object' ||
+            Array.isArray(config) ||
+            (config.settings !== undefined &&
+                (config.settings === null ||
+                    typeof config.settings !== 'object' ||
+                    Array.isArray(config.settings)))) {
+            return unavailable('Project configuration and settings must be objects');
+        }
+        if (config.settings?.git_integration === false) {
+            return {
+                name: NAME,
+                status: 'pass',
+                message: 'Commit evidence inspection skipped: Git integration is disabled',
+            };
+        }
+        // getConfig is deliberately lenient. Invalid intent must not turn into a false failure.
+        if (config.settings?.git_integration !== undefined &&
+            config.settings.git_integration !== true) {
+            return unavailable('settings.git_integration is not a boolean');
+        }
+        const requested = resolve(devstepsDir);
+        const actual = realpathSync.native(requested);
+        const root = realpathSync.native(dirname(requested));
+        if (basename(requested) !== '.devsteps' ||
+            relative(root, dirname(actual)) !== '' ||
+            basename(actual) !== '.devsteps') {
+            return unavailable('The served .devsteps directory does not belong directly to its workspace root');
+        }
+        findings = inspectCommitEvidence(root, [...hashes]);
+    }
+    catch (error) {
+        // Filesystem and JSON errors can embed arbitrary source text: retain only our Git-stage errors.
+        const reason = error instanceof SyntaxError
+            ? 'Project configuration is not valid JSON'
+            : error instanceof Error && !('code' in error)
+                ? error.message
+                : 'Local repository or project configuration is unavailable';
+        return unavailable(reason);
+    }
+    const counts = {
+        normal: 0,
+        archive: 0,
+        'local-only': 0,
+        unresolvable: 0,
+        incomplete: 0,
+    };
+    const samples = {
+        normal: [],
+        archive: [],
+        'local-only': [],
+        unresolvable: [],
+        incomplete: [],
+    };
+    for (const [id, item] of items) {
+        for (const hash of new Set(item.commits)) {
+            const finding = findings.get(hash);
+            if (!finding)
+                return unavailable('A requested commit was omitted from the inspection');
+            counts[finding.state]++;
+            if (finding.state !== 'normal' && samples[finding.state].length < MAX_REPORTED) {
+                samples[finding.state].push(`${id}: ${hash} — ${LABELS[finding.state]}${finding.reason ? ` (${finding.reason})` : ''}`);
+            }
+        }
+    }
+    const status = counts.unresolvable > 0
+        ? 'fail'
+        : counts['local-only'] + counts.incomplete > 0
+            ? 'warn'
+            : 'pass';
+    const details = [
+        ...samples.unresolvable,
+        ...samples.incomplete,
+        ...samples['local-only'],
+        ...samples.archive,
+    ].slice(0, MAX_REPORTED);
+    const detailCount = counts.unresolvable + counts.incomplete + counts['local-only'] + counts.archive;
+    if (detailCount > details.length)
+        details.push(`… and ${detailCount - details.length} more reference(s)`);
+    return {
+        name: NAME,
+        status,
+        message: `${counts.normal} normal-ref reachable, ${counts.archive} archive-ref reachable, ${counts['local-only']} local-only, ${counts.unresolvable} locally unresolvable, ${counts.incomplete} incomplete item commit reference(s); ${hashes.size} distinct SHA(s). Local inspection only.`,
+        ...(details.length > 0 ? { details } : {}),
+        ...(status !== 'pass'
+            ? {
+                fix: 'Check the original history or retained archive refs locally. This diagnostic never fetches, imports or rewrites commit evidence.',
+            }
+            : {}),
+    };
+}
+//# sourceMappingURL=doctor-commit-evidence.js.map

package/dist/core/doctor-commit-evidence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-commit-evidence.js","sourceRoot":"","sources":["../../src/core/doctor-commit-evidence.ts"],"names":[],"mappings":"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"}

package/dist/core/doctor-coordination.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Doctor check for coordination text in work items (BUG-153 P3, TASK-958).
+ *
+ * Reports work items that carry session-log sections, session addresses, rosters, or
+ * pasted message headers; work items tagged `handover`; and work items whose
+ * description has grown past a size or dated-section limit, which is the trace of a
+ * description used as an append-only log. Everything is a warning: the doctor never
+ * rewrites an item, and the fix is a move into the role's handover doc.
+ */
+import type { ItemMetadata } from '../schemas/index.js';
+import type { CheckResult } from './doctor-types.js';
+/** Default size budget before a work-item description is reported as a likely log. */
+export declare const LARGE_DESCRIPTION_BYTES: number;
+/** A work item with more dated sections than this is reported as a likely log. */
+export declare const MAX_DATED_SECTIONS = 10;
+export declare function detectCoordinationTextInItems(devstepsDir: string, items: ReadonlyMap<string, ItemMetadata>): CheckResult;
+//# sourceMappingURL=doctor-coordination.d.ts.map

package/dist/core/doctor-coordination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-coordination.d.ts","sourceRoot":"","sources":["../../src/core/doctor-coordination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAQxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,sFAAsF;AACtF,eAAO,MAAM,uBAAuB,QAAY,CAAC;AAKjD,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAmDrC,wBAAgB,6BAA6B,CAC3C,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,YAAY,CAAC,GACvC,WAAW,CA0Bb"}

package/dist/core/doctor-coordination.js

@@ -0,0 +1,88 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Doctor check for coordination text in work items (BUG-153 P3, TASK-958).
+ *
+ * Reports work items that carry session-log sections, session addresses, rosters, or
+ * pasted message headers; work items tagged `handover`; and work items whose
+ * description has grown past a size or dated-section limit, which is the trace of a
+ * description used as an append-only log. Everything is a warning: the doctor never
+ * rewrites an item, and the fix is a move into the role's handover doc.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { detectCoordinationText, HANDOVER_TAG, isWorkItemType, projectSlugFromDevstepsDir, } from './coordination-text.js';
+import { itemPaths } from './item-paths.js';
+/** Default size budget before a work-item description is reported as a likely log. */
+export const LARGE_DESCRIPTION_BYTES = 32 * 1024;
+/** Lasting decision registers get more room while retaining all other log checks. */
+const LARGE_DECISION_DESCRIPTION_BYTES = 64 * 1024;
+/** A work item with more dated sections than this is reported as a likely log. */
+export const MAX_DATED_SECTIONS = 10;
+const DATED_HEADING = /^#{2,3}\s.*\b20\d\d-\d\d-\d\d\b/;
+const MAX_REPORTED = 10;
+function countDatedSections(markdown) {
+    return markdown.split(/\r?\n/).filter((line) => DATED_HEADING.test(line)).length;
+}
+function describeFindings(findings) {
+    const counts = new Map();
+    for (const finding of findings)
+        counts.set(finding.kind, (counts.get(finding.kind) ?? 0) + 1);
+    const parts = [...counts].map(([kind, count]) => `${count} ${kind}`);
+    return `${parts.join(', ')} (first at line ${findings[0].line}: "${findings[0].text}")`;
+}
+function inspectItem(devstepsDir, meta, projectSlug) {
+    const problems = [];
+    let weight = 0;
+    if (meta.tags.includes(HANDOVER_TAG)) {
+        problems.push(`is a ${meta.type} tagged "${HANDOVER_TAG}"`);
+        weight += 1;
+    }
+    const path = itemPaths(devstepsDir, meta.id).description;
+    const markdown = existsSync(path) ? readFileSync(path, 'utf-8') : '';
+    const findings = detectCoordinationText(markdown, { projectSlug });
+    if (findings.length > 0) {
+        problems.push(`coordination text: ${describeFindings(findings)}`);
+        weight += findings.length;
+    }
+    const bytes = Buffer.byteLength(markdown, 'utf-8');
+    const budget = meta.type === 'decision' ? LARGE_DECISION_DESCRIPTION_BYTES : LARGE_DESCRIPTION_BYTES;
+    if (bytes > budget) {
+        problems.push(`description is ${Math.round(bytes / 1024)} KB`);
+        weight += 1;
+    }
+    const dated = countDatedSections(markdown);
+    if (dated > MAX_DATED_SECTIONS) {
+        problems.push(`${dated} dated sections`);
+        weight += 1;
+    }
+    return { id: meta.id, problems, weight };
+}
+export function detectCoordinationTextInItems(devstepsDir, items) {
+    const projectSlug = projectSlugFromDevstepsDir(devstepsDir);
+    const reports = [...items.values()]
+        .filter((meta) => isWorkItemType(meta.type))
+        .map((meta) => inspectItem(devstepsDir, meta, projectSlug))
+        .filter((report) => report.problems.length > 0)
+        .sort((a, b) => b.weight - a.weight || a.id.localeCompare(b.id, 'en', { numeric: true }));
+    if (reports.length === 0) {
+        return {
+            name: 'Coordination Text',
+            status: 'pass',
+            message: 'No work item carries handover, dispatch, roster, or session-log text',
+        };
+    }
+    const details = reports
+        .slice(0, MAX_REPORTED)
+        .map((report) => `${report.id}: ${report.problems.join('; ')}`);
+    if (reports.length > MAX_REPORTED)
+        details.push(`… and ${reports.length - MAX_REPORTED} more`);
+    return {
+        name: 'Coordination Text',
+        status: 'warn',
+        message: `${reports.length} work item(s) carry coordination state or have grown into a log`,
+        details,
+        fix: `Move queue order, dispatch state, rosters, and handovers into the role's handover doc (a doc tagged "${HANDOVER_TAG}") with update, and keep decisions, evidence, and commits on the work item.`,
+    };
+}
+//# sourceMappingURL=doctor-coordination.js.map

package/dist/core/doctor-coordination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-coordination.js","sourceRoot":"","sources":["../../src/core/doctor-coordination.ts"],"names":[],"mappings":"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"}

package/dist/core/doctor-counters.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Doctor check for ID counters that fell behind the IDs on disk (STORY-428).
+ *
+ * Two branches that both created items merge into a `counters.json` below the
+ * highest ID one of them allocated. `add` already allocates above the highest ID on
+ * disk, so nothing breaks — but the file is stale and says so here.
+ */
+import type { CheckResult } from './doctor-types.js';
+export declare function detectCountersBehindDisk(devstepsDir: string): CheckResult;
+//# sourceMappingURL=doctor-counters.d.ts.map

package/dist/core/doctor-counters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-counters.d.ts","sourceRoot":"","sources":["../../src/core/doctor-counters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAkCzE"}

package/dist/core/doctor-counters.js

@@ -0,0 +1,46 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Doctor check for ID counters that fell behind the IDs on disk (STORY-428).
+ *
+ * Two branches that both created items merge into a `counters.json` below the
+ * highest ID one of them allocated. `add` already allocates above the highest ID on
+ * disk, so nothing breaks — but the file is stale and says so here.
+ */
+import { getTypePrefix, TYPE_TO_DIRECTORY } from '../utils/index.js';
+import { highestIdOnDisk, loadCounters } from './counters.js';
+export function detectCountersBehindDisk(devstepsDir) {
+    let counters;
+    try {
+        counters = loadCounters(devstepsDir);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        return {
+            name: 'ID Counters',
+            status: 'fail',
+            message: `index/counters.json is unreadable: ${reason}`,
+            fix: 'Run: devsteps migrate — it rewrites the counters from the IDs on disk',
+        };
+    }
+    const behind = [];
+    for (const type of Object.keys(TYPE_TO_DIRECTORY)) {
+        const prefix = getTypePrefix(type);
+        const highest = highestIdOnDisk(devstepsDir, type);
+        const counter = counters[prefix] ?? 0;
+        if (counter < highest)
+            behind.push(`${prefix}: counter ${counter}, highest ID on disk ${highest}`);
+    }
+    if (behind.length === 0) {
+        return { name: 'ID Counters', status: 'pass', message: 'Every counter covers the IDs on disk' };
+    }
+    return {
+        name: 'ID Counters',
+        status: 'warn',
+        message: `${behind.length} counter(s) below the highest ID on disk — typical after a branch merge`,
+        details: behind,
+        fix: 'Nothing is at risk: add allocates above the highest ID on disk and raises the counter',
+    };
+}
+//# sourceMappingURL=doctor-counters.js.map

package/dist/core/doctor-counters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-counters.js","sourceRoot":"","sources":["../../src/core/doctor-counters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAG9D,MAAM,UAAU,wBAAwB,CAAC,WAAmB;IAC1D,IAAI,QAAgC,CAAC;IACrC,IAAI,CAAC;QACH,QAAQ,GAAG,YAAY,CAAC,WAAW,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,sCAAsC,MAAM,EAAE;YACvD,GAAG,EAAE,uEAAuE;SAC7E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAe,EAAE,CAAC;QAChE,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,eAAe,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACnD,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACtC,IAAI,OAAO,GAAG,OAAO;YACnB,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,aAAa,OAAO,wBAAwB,OAAO,EAAE,CAAC,CAAC;IAChF,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC;IAClG,CAAC;IAED,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,GAAG,MAAM,CAAC,MAAM,yEAAyE;QAClG,OAAO,EAAE,MAAM;QACf,GAAG,EAAE,uFAAuF;KAC7F,CAAC;AACJ,CAAC"}

package/dist/core/doctor-generated-files.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Explicit removal of the optional generated setup guide (STORY-527, DEC-088).
+ * The only deletion target is SETUP.md; previews and refused operations write nothing.
+ */
+export interface GeneratedFileCandidate {
+    path: '.devsteps/SETUP.md';
+    reason: string;
+    size_bytes: number | null;
+    sha256: string | null;
+    removable: boolean;
+    removed: boolean;
+    refusal?: string;
+}
+export interface GeneratedFilesRepairResult {
+    mode: 'preview' | 'apply';
+    applied: boolean;
+    can_apply: boolean;
+    files: GeneratedFileCandidate[];
+    unresolved: string[];
+}
+/**
+ * Apply always plans from fresh reads. It checks the loaded source, stamp and path again
+ * immediately before unlink; filesystem calls do not provide a cross-process compare-and-swap.
+ * No historical preview, caller-supplied path, recursive deletion or Git mutation is accepted.
+ */
+export declare function repairGeneratedFiles(devstepsDir: string, options?: {
+    apply?: boolean;
+}): GeneratedFilesRepairResult;
+//# sourceMappingURL=doctor-generated-files.d.ts.map

package/dist/core/doctor-generated-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-generated-files.d.ts","sourceRoot":"","sources":["../../src/core/doctor-generated-files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAoBH,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,oBAAoB,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;IACnB,KAAK,EAAE,sBAAsB,EAAE,CAAC;IAChC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AA+HD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAChC,0BAA0B,CAoD5B"}

package/dist/core/doctor-generated-files.js

@@ -0,0 +1,178 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Explicit removal of the optional generated setup guide (STORY-527, DEC-088).
+ * The only deletion target is SETUP.md; previews and refused operations write nothing.
+ */
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, realpathSync, unlinkSync, } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { renderSetupMd } from '../utils/setup-guide.js';
+const GUIDE = 'SETUP.md';
+const REASON = 'Optional DevSteps-generated setup guide; removing it does not remove project data.';
+function isMissing(error) {
+    return error?.code === 'ENOENT';
+}
+function readRoot(devstepsDir) {
+    const path = resolve(devstepsDir);
+    if (basename(path) !== '.devsteps')
+        throw new Error('Expected the project .devsteps directory.');
+    const stamp = lstatSync(path);
+    if (stamp.isSymbolicLink() || !stamp.isDirectory()) {
+        throw new Error('The .devsteps root must be a directory and cannot be a symbolic link.');
+    }
+    const real = realpathSync(path);
+    if (real !== join(realpathSync(dirname(path)), '.devsteps')) {
+        throw new Error('The .devsteps root escapes the project.');
+    }
+    return { path, real, dev: stamp.dev, ino: stamp.ino };
+}
+function assertRoot(root) {
+    const current = readRoot(root.path);
+    if (current.real !== root.real || current.dev !== root.dev || current.ino !== root.ino) {
+        throw new Error('The .devsteps root changed; preview again.');
+    }
+}
+function sameStamp(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.mode === right.mode &&
+        left.size === right.size &&
+        left.mtimeMs === right.mtimeMs &&
+        left.ctimeMs === right.ctimeMs);
+}
+function regularLeaf(root, name) {
+    const path = join(root.path, name);
+    const stamp = lstatSync(path);
+    if (stamp.isSymbolicLink() || !stamp.isFile()) {
+        throw new Error(`${name} must be a regular file and cannot be a symbolic link.`);
+    }
+    if (realpathSync(path) !== join(root.real, name)) {
+        throw new Error(`${name} escapes the .devsteps root.`);
+    }
+    return stamp;
+}
+/** Surround the descriptor read with identity checks; never follow a known link. */
+function readSnapshot(root, name, expected) {
+    assertRoot(root);
+    let before;
+    try {
+        before = regularLeaf(root, name);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        if (expected)
+            throw new Error(`${name} changed or disappeared; preview again.`);
+        return undefined;
+    }
+    const descriptor = openSync(join(root.path, name), constants.O_RDONLY | constants.O_NOFOLLOW);
+    let snapshot;
+    try {
+        const opened = fstatSync(descriptor);
+        if (!sameStamp(before, opened))
+            throw new Error(`${name} changed; preview again.`);
+        const bytes = readFileSync(descriptor);
+        const stamp = fstatSync(descriptor);
+        if (!sameStamp(opened, stamp))
+            throw new Error(`${name} changed; preview again.`);
+        snapshot = { bytes, stamp };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    assertRoot(root);
+    if (!sameStamp(snapshot.stamp, regularLeaf(root, name)) ||
+        (expected &&
+            (!sameStamp(expected.stamp, snapshot.stamp) || !expected.bytes.equals(snapshot.bytes)))) {
+        throw new Error(`${name} changed; preview again.`);
+    }
+    return snapshot;
+}
+function utf8(snapshot, name) {
+    const text = snapshot.bytes.toString('utf8');
+    if (!Buffer.from(text, 'utf8').equals(snapshot.bytes)) {
+        throw new Error(`${name} is not valid UTF-8.`);
+    }
+    return text;
+}
+function projectName(config) {
+    let value;
+    try {
+        value = JSON.parse(utf8(config, 'config.json'));
+    }
+    catch {
+        throw new Error('config.json must contain valid UTF-8 JSON and a project_name string.');
+    }
+    if (value === null ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        !('project_name' in value) ||
+        typeof value.project_name !== 'string') {
+        throw new Error('config.json must contain a project_name string.');
+    }
+    return value.project_name;
+}
+/**
+ * Apply always plans from fresh reads. It checks the loaded source, stamp and path again
+ * immediately before unlink; filesystem calls do not provide a cross-process compare-and-swap.
+ * No historical preview, caller-supplied path, recursive deletion or Git mutation is accepted.
+ */
+export function repairGeneratedFiles(devstepsDir, options = {}) {
+    const apply = options.apply === true;
+    const file = {
+        path: '.devsteps/SETUP.md',
+        reason: REASON,
+        size_bytes: null,
+        sha256: null,
+        removable: false,
+        removed: false,
+    };
+    const result = {
+        mode: apply ? 'apply' : 'preview',
+        applied: false,
+        can_apply: false,
+        files: [file],
+        unresolved: [],
+    };
+    try {
+        const root = readRoot(devstepsDir);
+        const guide = readSnapshot(root, GUIDE);
+        if (!guide) {
+            file.reason = 'Optional generated setup guide is absent; nothing to remove.';
+            return result;
+        }
+        file.size_bytes = guide.bytes.length;
+        file.sha256 = createHash('sha256').update(guide.bytes).digest('hex');
+        const config = readSnapshot(root, 'config.json');
+        if (!config)
+            throw new Error('config.json is missing; guide ownership cannot be recognized.');
+        const generated = renderSetupMd(projectName(config));
+        if (utf8(guide, GUIDE).replace(/\r\n/g, '\n') !== generated.replace(/\r\n/g, '\n')) {
+            throw new Error('SETUP.md has local edits or unrecognized content; removal is refused.');
+        }
+        file.removable = true;
+        result.can_apply = true;
+        if (!apply)
+            return result;
+        readSnapshot(root, 'config.json', config);
+        readSnapshot(root, GUIDE, guide);
+        assertRoot(root);
+        if (!sameStamp(guide.stamp, regularLeaf(root, GUIDE))) {
+            throw new Error('SETUP.md changed; preview again.');
+        }
+        unlinkSync(join(root.path, GUIDE));
+        file.removed = true;
+        result.applied = true;
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        file.refusal = reason;
+        file.removable = false;
+        result.can_apply = false;
+        result.unresolved.push(reason);
+    }
+    return result;
+}
+//# sourceMappingURL=doctor-generated-files.js.map

package/dist/core/doctor-generated-files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-generated-files.js","sourceRoot":"","sources":["../../src/core/doctor-generated-files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,SAAS,EACT,QAAQ,EACR,YAAY,EACZ,YAAY,EAEZ,UAAU,GACX,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAExD,MAAM,KAAK,GAAG,UAAU,CAAC;AACzB,MAAM,MAAM,GAAG,oFAAoF,CAAC;AAgCpG,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAQ,KAAsC,EAAE,IAAI,KAAK,QAAQ,CAAC;AACpE,CAAC;AAED,SAAS,QAAQ,CAAC,WAAmB;IACnC,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAClC,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,WAAW;QAAE,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACjG,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,KAAK,CAAC,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;QACnD,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;IAC3F,CAAC;IACD,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,IAAI,KAAK,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,CAAC;AACxD,CAAC;AAED,SAAS,UAAU,CAAC,IAAkB;IACpC,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,OAAO,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;QACvF,MAAM,IAAI,KAAK,CAAC,4CAA4C,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAAC,IAAW,EAAE,KAAY;IAC1C,OAAO,CACL,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG;QACtB,IAAI,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG;QACtB,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;QACxB,IAAI,CAAC,IAAI,KAAK,KAAK,CAAC,IAAI;QACxB,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO;QAC9B,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,OAAO,CAC/B,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAkB,EAAE,IAAY;IACnD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,KAAK,CAAC,cAAc,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,wDAAwD,CAAC,CAAC;IACnF,CAAC;IACD,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,8BAA8B,CAAC,CAAC;IACzD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,oFAAoF;AACpF,SAAS,YAAY,CACnB,IAAkB,EAClB,IAAgC,EAChC,QAAuB;IAEvB,UAAU,CAAC,IAAI,CAAC,CAAC;IACjB,IAAI,MAAa,CAAC;IAClB,IAAI,CAAC;QACH,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACnC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAC;QACnC,IAAI,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,yCAAyC,CAAC,CAAC;QAChF,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,QAAQ,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;IAC9F,IAAI,QAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;QACrC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,0BAA0B,CAAC,CAAC;QACnF,MAAM,KAAK,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;QACvC,MAAM,KAAK,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;QACpC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,0BAA0B,CAAC,CAAC;QAClF,QAAQ,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC9B,CAAC;YAAS,CAAC;QACT,SAAS,CAAC,UAAU,CAAC,CAAC;IACxB,CAAC;IACD,UAAU,CAAC,IAAI,CAAC,CAAC;IACjB,IACE,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACnD,CAAC,QAAQ;YACP,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EACzF,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,0BAA0B,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,IAAI,CAAC,QAAsB,EAAE,IAAY;IAChD,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,sBAAsB,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,WAAW,CAAC,MAAoB;IACvC,IAAI,KAAc,CAAC;IACnB,IAAI,CAAC;QACH,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC1F,CAAC;IACD,IACE,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACpB,CAAC,CAAC,cAAc,IAAI,KAAK,CAAC;QAC1B,OAAO,KAAK,CAAC,YAAY,KAAK,QAAQ,EACtC,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,KAAK,CAAC,YAAY,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,WAAmB,EACnB,OAAO,GAAwB,EAAE;IAEjC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC;IACrC,MAAM,IAAI,GAA2B;QACnC,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EAAE,MAAM;QACd,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,IAAI;QACZ,SAAS,EAAE,KAAK;QAChB,OAAO,EAAE,KAAK;KACf,CAAC;IACF,MAAM,MAAM,GAA+B;QACzC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS;QACjC,OAAO,EAAE,KAAK;QACd,SAAS,EAAE,KAAK;QAChB,KAAK,EAAE,CAAC,IAAI,CAAC;QACb,UAAU,EAAE,EAAE;KACf,CAAC;IACF,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAC;QACnC,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACxC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC,MAAM,GAAG,8DAA8D,CAAC;YAC7E,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACrE,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,+DAA+D,CAAC,CAAC;QAC9F,MAAM,SAAS,GAAG,aAAa,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;QACrD,IAAI,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;YACnF,MAAM,IAAI,KAAK,CAAC,uEAAuE,CAAC,CAAC;QAC3F,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,MAAM,CAAC,SAAS,GAAG,IAAI,CAAC;QACxB,IAAI,CAAC,KAAK;YAAE,OAAO,MAAM,CAAC;QAC1B,YAAY,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,CAAC,CAAC;QAC1C,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QACjC,UAAU,CAAC,IAAI,CAAC,CAAC;QACjB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;YACtD,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QACtD,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IACxB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,MAAM,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACtE,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACvB,MAAM,CAAC,SAAS,GAAG,KAAK,CAAC;QACzB,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/doctor-placeholders.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Read-only candidate detection; quoted examples can be intentional (STORY-530).
+ */
+import type { CheckResult } from './doctor-types.js';
+/** Inspect descriptions even when their metadata or the classification registry is unreadable. */
+export declare function detectPlaceholderCandidates(devstepsDir: string): CheckResult;
+//# sourceMappingURL=doctor-placeholders.d.ts.map

package/dist/core/doctor-placeholders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-placeholders.d.ts","sourceRoot":"","sources":["../../src/core/doctor-placeholders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAQrD,kGAAkG;AAClG,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAgC5E"}

package/dist/core/doctor-placeholders.js

@@ -0,0 +1,49 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Read-only candidate detection; quoted examples can be intentional (STORY-530).
+ */
+import { readFileSync } from 'node:fs';
+import { itemPaths } from './item-paths.js';
+import { listItemIds } from './item-store.js';
+const MAX_DETAILS = 10;
+const MAX_LINE_CHARS = 160;
+const candidate = /\{\{\s*new\b|\(QST(?:\s+of\s+this\s+review)?\)/i;
+/** Inspect descriptions even when their metadata or the classification registry is unreadable. */
+export function detectPlaceholderCandidates(devstepsDir) {
+    let count = 0;
+    const details = [];
+    for (const id of listItemIds(devstepsDir)) {
+        let description;
+        try {
+            description = readFileSync(itemPaths(devstepsDir, id).description, 'utf8');
+        }
+        catch {
+            continue; // Unreadable descriptions do not prevent scanning the remaining items.
+        }
+        for (const [index, line] of description.split(/\r?\n/).entries()) {
+            if (!candidate.test(line))
+                continue;
+            count++;
+            if (details.length < MAX_DETAILS) {
+                const shown = line.length > MAX_LINE_CHARS ? `${line.slice(0, MAX_LINE_CHARS)}…` : line;
+                details.push(`${id}:${index + 1}: ${shown}`);
+            }
+        }
+    }
+    return count === 0
+        ? {
+            name: 'Placeholder Candidates',
+            status: 'pass',
+            message: 'No unresolved item placeholder candidates found',
+        }
+        : {
+            name: 'Placeholder Candidates',
+            status: 'warn',
+            message: `${count} description line(s) contain possible unresolved item placeholders`,
+            details,
+            fix: 'Review the named descriptions and replace unintended placeholders with verified item IDs. Literal examples may be intentional; doctor never rewrites them.',
+        };
+}
+//# sourceMappingURL=doctor-placeholders.js.map

package/dist/core/doctor-placeholders.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor-placeholders.js","sourceRoot":"","sources":["../../src/core/doctor-placeholders.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C,MAAM,WAAW,GAAG,EAAE,CAAC;AACvB,MAAM,cAAc,GAAG,GAAG,CAAC;AAC3B,MAAM,SAAS,GAAG,iDAAiD,CAAC;AAEpE,kGAAkG;AAClG,MAAM,UAAU,2BAA2B,CAAC,WAAmB;IAC7D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,EAAE,IAAI,WAAW,CAAC,WAAW,CAAC,EAAE,CAAC;QAC1C,IAAI,WAAmB,CAAC;QACxB,IAAI,CAAC;YACH,WAAW,GAAG,YAAY,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QAC7E,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,CAAC,uEAAuE;QACnF,CAAC;QACD,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,WAAW,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;YACjE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,SAAS;YACpC,KAAK,EAAE,CAAC;YACR,IAAI,OAAO,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;gBACjC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;gBACxF,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,KAAK,GAAG,CAAC,KAAK,KAAK,EAAE,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,KAAK,CAAC;QAChB,CAAC,CAAC;YACE,IAAI,EAAE,wBAAwB;YAC9B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,iDAAiD;SAC3D;QACH,CAAC,CAAC;YACE,IAAI,EAAE,wBAAwB;YAC9B,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,GAAG,KAAK,oEAAoE;YACrF,OAAO;YACP,GAAG,EAAE,4JAA4J;SAClK,CAAC;AACR,CAAC"}