@planu/cli 5.3.67 → 5.3.69

package/dist/engine/saga/transition-cascade.js

@@ -5,6 +5,7 @@
 // to the prior status.
 import { runSaga } from './cascade-saga.js';
 import { transitionSpec } from '../spec-state-machine/transition-spec.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { appendTransitionEvent } from '../../storage/transition-log.js';
 // ---------------------------------------------------------------------------
 // Step definitions
@@ -30,6 +31,7 @@ function buildCascadeSteps(_ctx) {
                 if (!c.projectPath) {
                     return null; // No project path — Slack config unavailable
                 }
+                // eslint-disable-next-line no-restricted-syntax -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
                 const { getSlackConfig } = await import('../../storage/slack-store.js');
                 const slackConfig = await getSlackConfig(c.projectPath).catch(() => null);
                 if (!slackConfig?.webhookUrl) {
@@ -100,6 +102,7 @@ function buildCascadeSteps(_ctx) {
             // Errors are NOT caught here — the saga catches them and records a warning
             // because critical:false. The try/catch is intentionally absent.
             run: async (c) => {
+                // eslint-disable-next-line no-restricted-syntax -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
                 const { dispatchFeedbackEvent } = await import('../../tools/learn.js');
                 await dispatchFeedbackEvent(c.projectId, {
                     type: 'validate',

package/dist/engine/scan-project/index.js

@@ -9,6 +9,7 @@ import { calculateProjectHealth } from './health-scorer.js';
 import { generateProjectOverview } from './overview-generator.js';
 import { generateTeamPlan } from './team-planner.js';
 import { runDeepAnalysis } from '../reverse-engineer/index.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { createSpec, listSpecs } from '../../storage/spec-store.js';
 // Re-export submodules for barrel access
 export { discoverModules } from './module-discoverer.js';

package/dist/engine/scan-project/module-discoverer.js

@@ -1,4 +1,5 @@
 import { technologyValue } from '../technology-registry.js';
+import { fileExists } from '../../core/shared/fs.js';
 // engine/scan-project/module-discoverer.ts — Detects module boundaries in a project (SPEC-134)
 // Language-agnostic: supports monorepo, package-based, framework-based, and directory-based detection.
 import { readFile, readdir, stat } from 'node:fs/promises';
@@ -108,15 +109,6 @@ async function getSubdirs(dirPath) {
     return subdirs;
 }
 /** Checks if a file exists at the given path */
-async function fileExists(filePath) {
-    try {
-        await stat(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /** Reads a file safely, returns empty string on error */
 async function safeRead(filePath) {
     try {

package/dist/engine/schema-parity-auditor/handler-checker.js

@@ -1,6 +1,7 @@
 // engine/schema-parity-auditor/handler-checker.ts — Checks handler files for safe access patterns
 import { readFile } from 'node:fs/promises';
 import { glob } from 'glob';
+import { escapeRegex } from '../../core/shared/strings.js';
 /**
  * Finds the handler file for a given tool registration file.
  * Convention: register-foo-tools.ts → foo-handler.ts (or similar).
@@ -50,7 +51,4 @@ export function checkHandlerContent(fieldName, handlerFile, content) {
         hasIfCheck,
     };
 }
-function escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 //# sourceMappingURL=handler-checker.js.map

package/dist/engine/schema-parity-auditor/index.js

@@ -4,6 +4,7 @@ import { glob } from 'glob';
 import { scanZodOptionalFields } from './zod-scanner.js';
 import { checkTypeOptional } from './type-checker.js';
 import { findHandlerFile, checkHandlerAccess } from './handler-checker.js';
+import { escapeRegex } from '../../core/shared/strings.js';
 /**
  * Default type values to use when auto-fixing handlers.
  * Maps Zod base type → default value string.
@@ -112,7 +113,4 @@ async function fixTypeFile(fieldName, typeFile, dryRun) {
         preview: dryRun ? `- ${fieldName}: → ${fieldName}?:` : undefined,
     };
 }
-function escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 //# sourceMappingURL=index.js.map

package/dist/engine/schema-parity-auditor/type-checker.js

@@ -1,6 +1,7 @@
 // engine/schema-parity-auditor/type-checker.ts — Checks TypeScript types for optional mark
 import { readFile } from 'node:fs/promises';
 import { glob } from 'glob';
+import { escapeRegex } from '../../core/shared/strings.js';
 /**
  * Checks whether a given fieldName has an optional mark ("?") in any TypeScript type
  * file under projectPath/src/types/.
@@ -40,7 +41,4 @@ export function checkFieldInContent(fieldName, filePath, content) {
     }
     return { found: false, hasOptionalMark: false, typeFile: '' };
 }
-function escapeRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 //# sourceMappingURL=type-checker.js.map

package/dist/engine/self-healing/strategies/coverage-fix.js

@@ -1,6 +1,7 @@
 // engine/self-healing/strategies/coverage-fix.ts — SPEC-474: Coverage fix strategy
-import { readFile, writeFile, mkdir, access } from 'node:fs/promises';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname, basename, relative } from 'node:path';
+import { fileExists } from '../../../core/shared/fs.js';
 /**
  * Reads coverage/coverage-final.json and returns files with 0% statement coverage.
  */
@@ -74,15 +75,6 @@ describe('${moduleName}', () => {
 /**
  * Checks whether a file already exists on the filesystem.
  */
-async function fileExists(path) {
-    try {
-        await access(path);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 /**
  * Scaffolds a single test file for an uncovered source file.
  * Returns the relative test path on success, or null if skipped/failed.

package/dist/engine/session-context-generator.d.ts

@@ -1,3 +1,11 @@
+import type { Spec } from '../types/index.js';
+/**
+ * SPEC-1320: Renders session-context.md content from a supplied active-spec snapshot.
+ * Pure aside from reading project version and recent lessons — no file write.
+ */
+export declare function buildSessionContextContent(projectPath: string, allSpecs: Spec[], activeSpecs: Spec[]): Promise<string>;
+/** Absolute path to a project's generated session-context.md. */
+export declare function sessionContextPath(projectPath: string): string;
 /**
  * Auto-generates `planu/session-context.md` for a project.
  * Entirely best-effort: never throws, never blocks the caller.

package/dist/engine/session-context-generator.js

@@ -2,8 +2,10 @@
 // Writes planu/session-context.md so any LLM (Cursor, Windsurf, Aider…) can pick up project state.
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { specStore, lessonsStore } from '../storage/index.js';
 import { stableWriteGeneratedFile, stripSessionMarkdownVolatileFields, } from './generated-artifact-writer.js';
+import { deriveActiveSpecSnapshot } from './session-state/writer.js';
 /** Reads the `version` field from the project's package.json, or returns 'unknown'. */
 async function readProjectVersion(projectPath) {
     try {
@@ -46,10 +48,7 @@ function getPendingApproved(specs) {
 }
 /** Returns active in-progress specs ordered by most recently updated first. */
 function getActiveSpecs(specs) {
-    return specs
-        .filter((s) => s.status === 'implementing' || s.status === 'review')
-        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
-        .slice(0, 5);
+    return deriveActiveSpecSnapshot(specs);
 }
 /** Fetches the last 3 lessons for the project via lessonsStore (best-effort). */
 async function fetchRecentLessons(projectPath) {
@@ -126,32 +125,43 @@ function buildMarkdown(params) {
         '*Generated by [Planu](https://planu.dev) — The complete SDD stack for AI agents*',
     ].join('\n');
 }
+/**
+ * SPEC-1320: Renders session-context.md content from a supplied active-spec snapshot.
+ * Pure aside from reading project version and recent lessons — no file write.
+ */
+export async function buildSessionContextContent(projectPath, allSpecs, activeSpecs) {
+    const [version, lessons] = await Promise.all([
+        readProjectVersion(projectPath),
+        fetchRecentLessons(projectPath),
+    ]);
+    const done = getRecentlyDone(allSpecs);
+    const approved = getPendingApproved(allSpecs);
+    return buildMarkdown({
+        version,
+        activeCount: activeSpecs.length,
+        doneCount: allSpecs.filter((s) => s.status === 'done').length,
+        approvedCount: approved.length,
+        activeRows: buildActiveRows(activeSpecs),
+        doneRows: buildDoneRows(done),
+        approvedRows: buildApprovedRows(approved),
+        lessonsContent: buildLessonsSection(lessons),
+        generatedAt: new Date().toISOString(),
+    });
+}
+/** Absolute path to a project's generated session-context.md. */
+export function sessionContextPath(projectPath) {
+    return join(projectPath, 'planu', 'session-context.md');
+}
 /**
  * Auto-generates `planu/session-context.md` for a project.
  * Entirely best-effort: never throws, never blocks the caller.
  */
 export async function generateSessionContext(projectPath, projectId) {
     try {
-        const [version, allSpecs, lessons] = await Promise.all([
-            readProjectVersion(projectPath),
-            specStore.listSpecs(projectId),
-            fetchRecentLessons(projectPath),
-        ]);
+        const allSpecs = await specStore.listSpecs(projectId);
         const active = getActiveSpecs(allSpecs);
-        const done = getRecentlyDone(allSpecs);
-        const approved = getPendingApproved(allSpecs);
-        const content = buildMarkdown({
-            version,
-            activeCount: active.length,
-            doneCount: allSpecs.filter((s) => s.status === 'done').length,
-            approvedCount: approved.length,
-            activeRows: buildActiveRows(active),
-            doneRows: buildDoneRows(done),
-            approvedRows: buildApprovedRows(approved),
-            lessonsContent: buildLessonsSection(lessons),
-            generatedAt: new Date().toISOString(),
-        });
-        const contextPath = join(projectPath, 'planu', 'session-context.md');
+        const content = await buildSessionContextContent(projectPath, allSpecs, active);
+        const contextPath = sessionContextPath(projectPath);
         const writeResult = await stableWriteGeneratedFile(contextPath, content, {
             equivalence: stripSessionMarkdownVolatileFields,
         });

package/dist/engine/session-state/session-artifact-refresher.d.ts

@@ -0,0 +1,7 @@
+import type { RefreshSessionArtifactsResult, SessionArtifactRefreshFailureCode } from '../../types/index.js';
+export declare class SessionArtifactRefreshError extends Error {
+    readonly code: SessionArtifactRefreshFailureCode;
+    constructor(code: SessionArtifactRefreshFailureCode);
+}
+export declare function refreshSessionArtifacts(projectPath: string, projectId: string): Promise<RefreshSessionArtifactsResult>;
+//# sourceMappingURL=session-artifact-refresher.d.ts.map

package/dist/engine/session-state/session-artifact-refresher.js

@@ -0,0 +1,140 @@
+import { readFile, writeFile, rename, unlink, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
+import { specStore } from '../../storage/index.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
+import { withFileLock } from '../../storage/file-mutex.js';
+import { stableJsonStringify, stripRootUpdatedAt, stripSessionMarkdownVolatileFields, withFinalNewline, } from '../generated-artifact-writer.js';
+import { buildSessionContextContent, sessionContextPath } from '../session-context-generator.js';
+import { buildSessionIndexPatch, deriveActiveSpecSnapshot, rootFile } from './writer.js';
+export class SessionArtifactRefreshError extends Error {
+    code;
+    constructor(code) {
+        super(`session-artifact-refresh-failed:${code}`);
+        this.name = 'SessionArtifactRefreshError';
+        this.code = code;
+        this.stack = undefined;
+    }
+}
+function isEnoent(err) {
+    return err instanceof Error && err.code === 'ENOENT';
+}
+async function prepareArtifact(finalPath, content, equivalence) {
+    const next = withFinalNewline(content);
+    let previous;
+    try {
+        previous = await readFile(finalPath, 'utf-8');
+    }
+    catch (err) {
+        if (!isEnoent(err)) {
+            throw new SessionArtifactRefreshError('STAGE_WRITE_FAILED');
+        }
+        previous = null;
+    }
+    let changed = true;
+    if (previous !== null) {
+        const stableNewline = previous.endsWith('\n') && !previous.endsWith('\n\n');
+        if (previous === next || (stableNewline && equivalence(previous) === equivalence(next))) {
+            changed = false;
+        }
+    }
+    return {
+        finalPath,
+        content: next,
+        tmpPath: `${finalPath}.tmp.${process.pid.toString()}.${randomBytes(4).toString('hex')}`,
+        changed,
+        previous,
+    };
+}
+async function cleanupTmp(artifacts) {
+    await Promise.all(artifacts.map((artifact) => unlink(artifact.tmpPath).catch(() => {
+        /* best-effort cleanup */
+    })));
+}
+async function restorePrevious(artifact) {
+    try {
+        if (artifact.previous === null) {
+            await unlink(artifact.finalPath);
+        }
+        else {
+            await writeFile(artifact.finalPath, artifact.previous, 'utf-8');
+        }
+    }
+    catch {
+        /* best-effort rollback */
+    }
+}
+async function commitPair(sessionJson, sessionContext) {
+    const staged = [sessionJson, sessionContext].filter((artifact) => artifact.changed);
+    if (staged.length === 0) {
+        return;
+    }
+    try {
+        await mkdir(dirname(sessionJson.finalPath), { recursive: true });
+    }
+    catch {
+        throw new SessionArtifactRefreshError('STAGE_WRITE_FAILED');
+    }
+    const writeOutcomes = await Promise.allSettled(staged.map((artifact) => writeFile(artifact.tmpPath, artifact.content, 'utf-8')));
+    const anyWriteFailed = writeOutcomes.some((outcome) => outcome.status === 'rejected');
+    if (anyWriteFailed) {
+        await cleanupTmp(staged);
+        throw new SessionArtifactRefreshError('STAGE_WRITE_FAILED');
+    }
+    const committed = [];
+    try {
+        for (const artifact of staged) {
+            await rename(artifact.tmpPath, artifact.finalPath);
+            committed.push(artifact);
+        }
+    }
+    catch {
+        await Promise.all(committed.map((artifact) => restorePrevious(artifact)));
+        await cleanupTmp(staged.filter((artifact) => !committed.includes(artifact)));
+        throw new SessionArtifactRefreshError('COMMIT_FAILED');
+    }
+}
+async function refreshLocked(projectPath, projectId) {
+    const allSpecs = await specStore.listSpecs(projectId);
+    const activeSpecs = deriveActiveSpecSnapshot(allSpecs);
+    const sessionJsonPath = rootFile(projectPath);
+    const contextMdPath = sessionContextPath(projectPath);
+    let existingIndex = { activeSpecs: [], updatedAt: '' };
+    try {
+        existingIndex = JSON.parse(await readFile(sessionJsonPath, 'utf-8'));
+    }
+    catch {
+        /* start fresh */
+    }
+    const nextIndex = buildSessionIndexPatch(existingIndex, allSpecs);
+    const sessionContextContent = await buildSessionContextContent(projectPath, allSpecs, activeSpecs);
+    const sessionJsonArtifact = await prepareArtifact(sessionJsonPath, stableJsonStringify(nextIndex), stripRootUpdatedAt);
+    const sessionContextArtifact = await prepareArtifact(contextMdPath, sessionContextContent, stripSessionMarkdownVolatileFields);
+    try {
+        await commitPair(sessionJsonArtifact, sessionContextArtifact);
+    }
+    catch (err) {
+        if (err instanceof SessionArtifactRefreshError) {
+            throw err;
+        }
+        throw new SessionArtifactRefreshError('UNEXPECTED_FAILURE');
+    }
+    return {
+        activeSpecIds: nextIndex.activeSpecs,
+        sessionJsonWritten: sessionJsonArtifact.changed,
+        sessionContextWritten: sessionContextArtifact.changed,
+    };
+}
+export async function refreshSessionArtifacts(projectPath, projectId) {
+    try {
+        return await withFileLock(`session-artifacts:${projectPath}`, () => refreshLocked(projectPath, projectId));
+    }
+    catch (err) {
+        if (err instanceof SessionArtifactRefreshError) {
+            throw err;
+        }
+        throw new SessionArtifactRefreshError('UNEXPECTED_FAILURE');
+    }
+}
+//# sourceMappingURL=session-artifact-refresher.js.map

package/dist/engine/session-state/writer.d.ts

@@ -1,4 +1,5 @@
 import type { SpecSessionState, SessionIndex, Spec } from '../../types/index.js';
+export declare function rootFile(projectPath: string): string;
 /**
  * SPEC-633: Write per-spec session state and update root session.json index.
  * Best-effort — never throws.
@@ -6,6 +7,8 @@ import type { SpecSessionState, SessionIndex, Spec } from '../../types/index.js'
 export declare function writeSpecSessionState(projectPath: string, specId: string, specTitle: string, lastAction: string, testsStatus?: SpecSessionState['testsStatus'], contextUsage?: number): Promise<void>;
 /** SPEC-656: Compute epicProgress map from all project specs. Tags shared by >=3 specs are epics. */
 export declare function computeEpicProgress(specs: Spec[]): Record<string, string>;
+export declare function deriveActiveSpecSnapshot(specs: Spec[]): Spec[];
+export declare function buildSessionIndexPatch(existingIndex: SessionIndex, specs: Spec[]): SessionIndex;
 /**
  * SPEC-656: Update epicProgress in root session.json after any status change.
  * Best-effort — never throws.

package/dist/engine/session-state/writer.js

@@ -12,7 +12,7 @@ function stateDir(projectPath) {
 function specFile(projectPath, specId) {
     return join(stateDir(projectPath), `session-${specId}.json`);
 }
-function rootFile(projectPath) {
+export function rootFile(projectPath) {
     return join(projectPath, 'planu', ROOT_SESSION);
 }
 function getModifiedFiles(projectPath) {
@@ -123,13 +123,39 @@ export function computeEpicProgress(specs) {
     }
     return progress;
 }
-function reconcileActiveSpecIds(existing, specs) {
-    const activeFromSpecs = specs
+const ACTIVE_SPEC_LIMIT = 5;
+export function deriveActiveSpecSnapshot(specs) {
+    const sorted = specs
         .filter((spec) => spec.status === 'implementing' || spec.status === 'review')
-        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))
-        .map((spec) => spec.id);
-    const knownActive = new Set(activeFromSpecs);
-    return [...new Set(existing.filter((specId) => knownActive.has(specId)).concat(activeFromSpecs))];
+        .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || b.id.localeCompare(a.id));
+    const seenIds = new Set();
+    const deduped = [];
+    for (const spec of sorted) {
+        if (seenIds.has(spec.id)) {
+            continue;
+        }
+        seenIds.add(spec.id);
+        deduped.push(spec);
+    }
+    return deduped.slice(0, ACTIVE_SPEC_LIMIT);
+}
+function reconcileActiveSpecIds(specs) {
+    return deriveActiveSpecSnapshot(specs).map((spec) => spec.id);
+}
+export function buildSessionIndexPatch(existingIndex, specs) {
+    const epicProgress = computeEpicProgress(specs);
+    const next = {
+        ...existingIndex,
+        activeSpecs: reconcileActiveSpecIds(specs),
+        updatedAt: new Date().toISOString(),
+    };
+    if (Object.keys(epicProgress).length === 0) {
+        delete next.epicProgress;
+    }
+    else {
+        next.epicProgress = epicProgress;
+    }
+    return next;
 }
 /**
  * SPEC-656: Update epicProgress in root session.json after any status change.
@@ -137,7 +163,6 @@ function reconcileActiveSpecIds(existing, specs) {
  */
 export async function updateEpicProgressInSession(projectPath, specs) {
     try {
-        const epicProgress = computeEpicProgress(specs);
         const filePath = rootFile(projectPath);
         let existingContent = null;
         let index = { activeSpecs: [], updatedAt: '' };
@@ -148,15 +173,8 @@ export async function updateEpicProgressInSession(projectPath, specs) {
         catch {
             /* start fresh */
         }
-        index.activeSpecs = reconcileActiveSpecIds(index.activeSpecs, specs);
-        if (Object.keys(epicProgress).length === 0) {
-            delete index.epicProgress;
-        }
-        else {
-            index.epicProgress = epicProgress;
-        }
-        index.updatedAt = new Date().toISOString();
-        await stableWriteGeneratedFile(filePath, stableJsonStringify(index), {
+        const next = buildSessionIndexPatch(index, specs);
+        await stableWriteGeneratedFile(filePath, stableJsonStringify(next), {
             equivalence: stripRootUpdatedAt,
             existingContent,
         });

package/dist/engine/shared-agent-memory.js

@@ -1,6 +1,7 @@
 // engine/shared-agent-memory.ts — SPEC-689
 import { readFile, mkdir, rename } from 'node:fs/promises';
 import { join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashProjectPath, projectDataDir } from '../storage/base-store.js';
 import { acquireLock, releaseLock } from '../engine/safety/file-mutex.js';
 import { atomicWriteFile } from '../engine/safety/atomic-write-file.js';

package/dist/engine/skill-adapter/index.js

@@ -2,10 +2,13 @@
 // Replaces placeholders and rewrites commands based on ProjectKnowledge.
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { readSkillRegistry, writeSkillRegistryEntry, } from '../../storage/skill-registry-storage.js';
 import { PLACEHOLDER_MAP } from './placeholder-map.js';
 import { rewritePackageManagerCommands, rewriteTestRunnerCommands } from './command-rewriter.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashProjectPath } from '../../storage/base-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { resolveStorageLayout } from '../../storage/storage-layout.js';
 export { PLACEHOLDER_MAP } from './placeholder-map.js';
 export { rewritePackageManagerCommands, rewriteTestRunnerCommands } from './command-rewriter.js';

package/dist/engine/skill-bootstrap/registry-fetcher.js

@@ -1,3 +1,4 @@
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { getSkillBootstrapConfig } from '../../storage/skill-bootstrap-store.js';
 import { detectProjectStack, matchTechsToAvailable } from './stack-matcher.js';
 const FETCH_TIMEOUT_MS = 5000;

package/dist/engine/skill-bootstrap/skill-writer.js

@@ -1,7 +1,8 @@
 // engine/skill-bootstrap/skill-writer.ts — SPEC-439: Write skills to target AI tool files
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { writeFile, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { assertEnglishOnlyArtifactText } from '../spec-language/english-only.js';
+import { readFileOrNull as readFileSafe } from '../../core/shared/fs.js';
 const AUTO_SECTION_HEADER = '## Auto-installed Skills (Planu)';
 function targetToRelativePath(target) {
     switch (target) {
@@ -23,14 +24,6 @@ function targetToRelativePath(target) {
         }
     }
 }
-async function readFileSafe(filePath) {
-    try {
-        return await readFile(filePath, 'utf-8');
-    }
-    catch {
-        return null;
-    }
-}
 export function formatSkillsForTarget(skills, target) {
     if (target === 'cursorrules' || target === 'windsurfrules' || target === 'clinerules') {
         return skills.map((s) => s.content).join('\n\n');

package/dist/engine/skill-bootstrap/stack-matcher.js

@@ -1,7 +1,7 @@
 import { technologyValue } from '../technology-registry.js';
 // engine/skill-bootstrap/stack-matcher.ts — SPEC-439: Detect project stack and match to skills
-import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+import { readFileOrNull as readFileSafe } from '../../core/shared/fs.js';
 const DEP_TO_TECH = {
     // Frontend frameworks
     next: technologyValue('technology-nextjs-c93379'),
@@ -114,14 +114,6 @@ const DEP_TO_TECH = {
     sqlalchemy: technologyValue('technology-sqlalchemy-37f268'),
     pydantic: technologyValue('technology-pydantic-636623'),
 };
-async function readFileSafe(filePath) {
-    try {
-        return await readFile(filePath, 'utf-8');
-    }
-    catch {
-        return null;
-    }
-}
 async function detectFromPackageJson(projectPath) {
     const content = await readFileSafe(join(projectPath, 'package.json'));
     if (!content) {

package/dist/engine/skill-discovery/multi-agent-writer.d.ts

@@ -1,4 +1,5 @@
 import type { SkillWriteTarget, WrittenSkillFile } from '../../types/skill-generation.js';
+/** Check if a file exists on disk. */
 /**
  * Write skill content to the appropriate locations for each requested agent.
  *

package/dist/engine/skill-discovery/multi-agent-writer.js

@@ -2,6 +2,7 @@
 // Maps skill content to the file location expected by each supported AI agent/IDE.
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import { fileExists } from '../../core/shared/fs.js';
 // ---------------------------------------------------------------------------
 // Agent path resolvers
 // ---------------------------------------------------------------------------
@@ -74,15 +75,6 @@ function replaceSection(fileContent, skillName, newSection) {
     return (fileContent.slice(0, start) + newSection.trimStart() + fileContent.slice(end + endMarker.length));
 }
 /** Check if a file exists on disk. */
-async function fileExists(filePath) {
-    try {
-        await fs.access(filePath);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------

package/dist/engine/skill-generator/workflow-skill-generator.js

@@ -6,6 +6,7 @@ import { technologyValue } from '../technology-registry.js';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { adaptSkillContent } from '../skill-adapter/index.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { writeSkillRegistryEntry } from '../../storage/skill-registry-storage.js';
 import { WORKFLOW_SKILL_DEFINITIONS } from './skill-definitions.js';
 import { hashConventions } from './conventions-hasher.js';

package/dist/engine/skill-registry/ttl-refresh.js

@@ -3,7 +3,9 @@
 import { readFile, writeFile, mkdir, appendFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { fetchAnthropicSkillContent } from './anthropic-adapter.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashProjectPath } from '../../storage/base-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { resolveStorageLayout } from '../../storage/storage-layout.js';
 const TTL_MS = 30 * 24 * 60 * 60 * 1000;
 const SKILLS_DIR = '.claude/skills';

package/dist/engine/spec-audit/index.js

@@ -1,7 +1,9 @@
 // engine/spec-audit/index.ts — SPEC-744
 // Orchestrates the two-tier spec drift audit.
 import { join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { listSpecs } from '../../storage/spec-store.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
 import { buildSpecGraph } from '../spec-dependency-graph/graph-builder.js';
 import { getSupersededSet, getSupersededMap } from '../spec-dependency-graph/superseded-set.js';

package/dist/engine/spec-audit/report-writer.js

@@ -4,6 +4,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
 import { atomicWriteFile } from '../safety/atomic-write-file.js';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { hashProjectPath, projectDataDir } from '../../storage/base-store.js';
 // ---------------------------------------------------------------------------
 // Markdown report

package/dist/engine/spec-coverage/core.js

@@ -2,6 +2,7 @@
 // Coordinates test-finder, criteria-mapper, scoring, and persistence.
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
+// eslint-disable-next-line no-restricted-imports -- grandfathered layer violation, remediation SPEC-1661 SPEC-1662 SPEC-1663
 import { readJson, writeJson, projectDataDir } from '../../storage/base-store.js';
 import { findTestFiles, detectTestRunners, readTestFileContent } from './test-finder.js';
 import { extractCriteria, mapTestsToCriterion } from './criteria-mapper.js';