@devtrack-solution/codesdd 1.2.3 → 1.2.4-rc3

package/dist/core/sdd/release-readiness.js

@@ -0,0 +1,472 @@
+import { existsSync } from 'node:fs';
+import { promises as fs } from 'node:fs';
+import { execFile } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { SddCheckCommand } from './check.js';
+import { loadProjectSddConfig, loadStateSnapshot, resolveSddPaths, } from './state.js';
+import { evaluatePackageSecurityGates } from './package-security-gates.js';
+const execFileAsync = promisify(execFile);
+const CI_PARITY_COMMANDS = [
+    'pnpm run build',
+    'pnpm run sdd:schema:check',
+    'pnpm exec tsc --noEmit',
+    'pnpm run lint',
+    'pnpm run sdd:validate:no-build',
+    'pnpm exec vitest run --testTimeout 30000',
+    'pnpm run check:pack-version',
+];
+const REQUIRED_SCRIPTS = [
+    'build',
+    'sdd:schema:check',
+    'sdd:validate:no-build',
+    'lint',
+    'test',
+    'check:pack-version',
+    'quality:review',
+];
+const REQUIRED_SCHEMA_FILES = [
+    'workspace-catalog.schema.json',
+    '5-quality.schema.json',
+    'agent-runtime-command-plan.schema.json',
+    'agent-runtime-opencode-run-evidence.schema.json',
+];
+const COVERAGE_TARGET_PERCENT = 95;
+export async function evaluateReleaseReadiness(projectRoot) {
+    const checks = [];
+    const packageJson = await readPackageJson(projectRoot);
+    const config = await loadProjectSddConfig(projectRoot);
+    const paths = resolveSddPaths(projectRoot, config);
+    const snapshot = await loadStateSnapshot(paths, config);
+    const sddCheck = await new SddCheckCommand().execute(projectRoot, { render: false, strict: true });
+    checks.push({
+        id: 'sdd-health',
+        status: sddCheck.valid ? 'pass' : 'fail',
+        summary: sddCheck.valid ? 'CodeSDD check is valid.' : 'CodeSDD check has blocking errors.',
+        evidence: sddCheck.valid ? undefined : sddCheck.errors.join(' | '),
+    });
+    const activeFeatures = snapshot.backlog.items.filter((item) => item.status === 'IN_PROGRESS').map((item) => item.id);
+    checks.push({
+        id: 'active-features',
+        status: activeFeatures.length === 0 ? 'pass' : 'fail',
+        summary: activeFeatures.length === 0 ? 'No active FEAT workspaces remain.' : 'Active FEAT workspaces remain.',
+        evidence: activeFeatures.join(', ') || undefined,
+    });
+    checks.push({
+        id: 'package-metadata',
+        status: packageJson.name === '@devtrack-solution/codesdd' &&
+            packageJson.license === 'MIT' &&
+            packageJson.bin?.codesdd === 'bin/codesdd.js'
+            ? 'pass'
+            : 'fail',
+        summary: 'Package name, license, and bin entry match release expectations.',
+        evidence: `${packageJson.name} ${packageJson.version}`,
+    });
+    const missingScripts = REQUIRED_SCRIPTS.filter((script) => !packageJson.scripts?.[script]);
+    checks.push({
+        id: 'release-scripts',
+        status: missingScripts.length === 0 ? 'pass' : 'fail',
+        summary: missingScripts.length === 0 ? 'Required release validation scripts are present.' : 'Required release validation scripts are missing.',
+        evidence: missingScripts.join(', ') || REQUIRED_SCRIPTS.join(', '),
+    });
+    checks.push(await evaluateGitWorkingTree(projectRoot));
+    checks.push(await evaluateCoverageEvidence(projectRoot));
+    checks.push(await evaluateNpmConfig(projectRoot));
+    checks.push(await evaluatePackageSecurity(projectRoot));
+    checks.push(await evaluateProvenanceAndSbom(projectRoot, packageJson));
+    checks.push(await evaluateTarballSmokeAndRollback(projectRoot, packageJson));
+    checks.push(await evaluateSchemaArtifacts(projectRoot));
+    checks.push(await evaluateReleaseDocs(projectRoot));
+    const blockers = checks
+        .filter((check) => check.status === 'fail')
+        .map((check) => `${check.id}: ${check.summary}${check.evidence ? ` (${check.evidence})` : ''}`);
+    const warnings = checks
+        .filter((check) => check.status === 'warn')
+        .map((check) => `${check.id}: ${check.summary}${check.evidence ? ` (${check.evidence})` : ''}`);
+    return {
+        schema_version: 1,
+        status: blockers.length > 0 ? 'blocked' : warnings.length > 0 ? 'warning' : 'ready',
+        generated_at: new Date().toISOString(),
+        blockers,
+        warnings,
+        checks,
+        ci_parity_commands: CI_PARITY_COMMANDS,
+    };
+}
+async function evaluateGitWorkingTree(projectRoot) {
+    if (!existsSync(path.join(projectRoot, '.git'))) {
+        return {
+            id: 'git-working-tree',
+            status: 'warn',
+            summary: 'Git working tree could not be verified because .git is absent.',
+            evidence: '.git',
+        };
+    }
+    try {
+        const { stdout } = await execFileAsync('git', ['status', '--porcelain=v1', '--untracked-files=all'], {
+            cwd: projectRoot,
+            maxBuffer: 1024 * 1024,
+        });
+        const entries = stdout.split(/\r?\n/u).filter(Boolean);
+        return {
+            id: 'git-working-tree',
+            status: entries.length === 0 ? 'pass' : 'fail',
+            summary: entries.length === 0 ? 'Working tree is clean.' : 'Working tree has uncommitted or untracked files.',
+            evidence: entries.slice(0, 12).join(' | ') || undefined,
+        };
+    }
+    catch (error) {
+        return {
+            id: 'git-working-tree',
+            status: 'warn',
+            summary: 'Git working tree could not be verified.',
+            evidence: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+async function evaluateCoverageEvidence(projectRoot) {
+    const coveragePath = path.join(projectRoot, 'coverage', 'coverage-final.json');
+    if (!existsSync(coveragePath)) {
+        return {
+            id: 'coverage-evidence',
+            status: 'fail',
+            summary: 'Coverage evidence is missing.',
+            evidence: 'coverage/coverage-final.json',
+        };
+    }
+    try {
+        const coverage = JSON.parse(await fs.readFile(coveragePath, 'utf-8'));
+        const changedSourceScope = await listChangedSourceScope(projectRoot);
+        const touchedCoverage = summarizeCoverage(coverage, projectRoot, changedSourceScope);
+        const globalCoverage = summarizeCoverage(coverage, projectRoot);
+        const failingMetrics = ['statements', 'lines', 'functions'].filter((metric) => touchedCoverage[metric].percent < COVERAGE_TARGET_PERCENT);
+        const branchDisposition = globalCoverage.branches.percent < COVERAGE_TARGET_PERCENT
+            ? `; global branches ${globalCoverage.branches.percent}% tracked as ratchet`
+            : '';
+        const scopeFiles = [...changedSourceScope.keys()].sort();
+        const scope = scopeFiles.length > 0 ? `touched:${scopeFiles.join(',')}` : 'global:src';
+        return {
+            id: 'coverage-evidence',
+            status: failingMetrics.length === 0 ? 'pass' : 'fail',
+            summary: failingMetrics.length === 0
+                ? 'Coverage evidence meets release target for touched source scope.'
+                : 'Coverage evidence is below release target for touched source scope.',
+            evidence: `${scope}; statements ${touchedCoverage.statements.percent}%, lines ${touchedCoverage.lines.percent}%, functions ${touchedCoverage.functions.percent}%${branchDisposition}`,
+        };
+    }
+    catch (error) {
+        return {
+            id: 'coverage-evidence',
+            status: 'fail',
+            summary: 'Coverage evidence could not be parsed.',
+            evidence: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export function formatReleaseReadinessReport(report) {
+    const lines = [`Release readiness: ${report.status}`, `Generated at: ${report.generated_at}`];
+    if (report.blockers.length > 0) {
+        lines.push('Blockers:');
+        for (const blocker of report.blockers)
+            lines.push(`- ${blocker}`);
+    }
+    if (report.warnings.length > 0) {
+        lines.push('Warnings:');
+        for (const warning of report.warnings)
+            lines.push(`- ${warning}`);
+    }
+    lines.push('Checks:');
+    for (const check of report.checks) {
+        lines.push(`- ${check.id}: ${check.status} - ${check.summary}${check.evidence ? ` (${check.evidence})` : ''}`);
+    }
+    lines.push('CI parity commands:');
+    for (const command of report.ci_parity_commands)
+        lines.push(`- ${command}`);
+    return lines.join('\n');
+}
+async function readPackageJson(projectRoot) {
+    const content = await fs.readFile(path.join(projectRoot, 'package.json'), 'utf-8');
+    return JSON.parse(content);
+}
+async function listChangedSourceScope(projectRoot) {
+    const changed = new Map();
+    if (!existsSync(path.join(projectRoot, '.git')))
+        return changed;
+    try {
+        const { stdout: status } = await execFileAsync('git', ['status', '--porcelain=v1', '--untracked-files=all'], {
+            cwd: projectRoot,
+            maxBuffer: 1024 * 1024,
+        });
+        for (const line of status.split(/\r?\n/u).filter(Boolean)) {
+            const statusCode = line.slice(0, 2);
+            const relativePath = line
+                .slice(3)
+                .trim()
+                .split(' -> ')
+                .at(-1) || '';
+            if (!/^src\/.*\.tsx?$/u.test(relativePath))
+                continue;
+            changed.set(path.normalize(relativePath), statusCode === '??' ? null : new Set());
+        }
+        await addDiffSourceLines(projectRoot, changed, ['diff', '--unified=0', '--', 'src']);
+        if (changed.size === 0) {
+            const upstreamBase = await resolveUpstreamDiffBase(projectRoot);
+            if (upstreamBase) {
+                await addDiffSourceLines(projectRoot, changed, ['diff', '--unified=0', `${upstreamBase}...HEAD`, '--', 'src']);
+            }
+        }
+    }
+    catch {
+        return changed;
+    }
+    return changed;
+}
+async function resolveUpstreamDiffBase(projectRoot) {
+    try {
+        const { stdout: upstreamStdout } = await execFileAsync('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], {
+            cwd: projectRoot,
+            maxBuffer: 1024 * 1024,
+        });
+        const upstream = upstreamStdout.trim();
+        if (!upstream)
+            return undefined;
+        const [{ stdout: baseStdout }, { stdout: headStdout }] = await Promise.all([
+            execFileAsync('git', ['merge-base', 'HEAD', upstream], {
+                cwd: projectRoot,
+                maxBuffer: 1024 * 1024,
+            }),
+            execFileAsync('git', ['rev-parse', 'HEAD'], {
+                cwd: projectRoot,
+                maxBuffer: 1024 * 1024,
+            }),
+        ]);
+        const base = baseStdout.trim();
+        const head = headStdout.trim();
+        return base && base !== head ? base : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function addDiffSourceLines(projectRoot, changed, diffArgs) {
+    const { stdout: diff } = await execFileAsync('git', diffArgs, {
+        cwd: projectRoot,
+        maxBuffer: 1024 * 1024,
+    });
+    let currentFile = '';
+    let newLine = 0;
+    for (const line of diff.split(/\r?\n/u)) {
+        if (line.startsWith('+++ b/')) {
+            currentFile = path.normalize(line.slice('+++ b/'.length));
+            if (/^src[/\\].*\.tsx?$/u.test(currentFile) && !changed.has(currentFile)) {
+                changed.set(currentFile, new Set());
+            }
+            continue;
+        }
+        const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/u);
+        if (hunk) {
+            newLine = Number(hunk[1]);
+            continue;
+        }
+        if (!currentFile || !changed.has(currentFile) || changed.get(currentFile) === null)
+            continue;
+        if (line.startsWith('+') && !line.startsWith('+++')) {
+            changed.get(currentFile)?.add(newLine);
+            newLine += 1;
+        }
+        else if (!line.startsWith('-')) {
+            newLine += 1;
+        }
+    }
+}
+function summarizeCoverage(coverage, projectRoot, changedSourceScope = new Map()) {
+    const totals = {
+        statements: { covered: 0, total: 0, percent: 100 },
+        branches: { covered: 0, total: 0, percent: 100 },
+        functions: { covered: 0, total: 0, percent: 100 },
+        lines: { covered: 0, total: 0, percent: 100 },
+    };
+    for (const [absolutePath, fileCoverage] of Object.entries(coverage)) {
+        const relativePath = path.normalize(path.relative(projectRoot, fileCoverage.path || absolutePath));
+        const isSource = relativePath.startsWith(`src${path.sep}`) && /\.tsx?$/u.test(relativePath);
+        if (!isSource)
+            continue;
+        const changedLines = changedSourceScope.get(relativePath);
+        if (changedSourceScope.size > 0 && changedLines === undefined)
+            continue;
+        const lineHits = new Map();
+        for (const [statementId, count] of Object.entries(fileCoverage.s || {})) {
+            const line = fileCoverage.statementMap?.[statementId]?.start?.line;
+            if (changedLines && (line === undefined || !changedLines.has(line)))
+                continue;
+            totals.statements.total += 1;
+            if (count > 0)
+                totals.statements.covered += 1;
+            if (line !== undefined) {
+                lineHits.set(line, (lineHits.get(line) || 0) + (count > 0 ? 1 : 0));
+            }
+        }
+        for (const [functionId, count] of Object.entries(fileCoverage.f || {})) {
+            const line = fileCoverage.fnMap?.[functionId]?.decl?.start?.line || fileCoverage.fnMap?.[functionId]?.loc?.start?.line;
+            if (changedLines && (line === undefined || !changedLines.has(line)))
+                continue;
+            totals.functions.total += 1;
+            if (count > 0)
+                totals.functions.covered += 1;
+        }
+        for (const counts of Object.values(fileCoverage.b || {})) {
+            for (const count of counts) {
+                totals.branches.total += 1;
+                if (count > 0)
+                    totals.branches.covered += 1;
+            }
+        }
+        for (const count of lineHits.values()) {
+            totals.lines.total += 1;
+            if (count > 0)
+                totals.lines.covered += 1;
+        }
+    }
+    for (const metric of Object.values(totals)) {
+        metric.percent = roundPercent(metric.covered, metric.total);
+    }
+    return totals;
+}
+function roundPercent(covered, total) {
+    return total === 0 ? 100 : Number(((covered / total) * 100).toFixed(2));
+}
+async function evaluateNpmConfig(projectRoot) {
+    const npmrcPath = path.join(projectRoot, '.npmrc');
+    const gitignorePath = path.join(projectRoot, '.gitignore');
+    const gitignore = await fs.readFile(gitignorePath, 'utf-8').catch(() => '');
+    const npmrcIgnored = gitignore.split(/\r?\n/u).some((line) => line.trim() === '.npmrc');
+    if (existsSync(npmrcPath)) {
+        return {
+            id: 'npmrc-secret-boundary',
+            status: 'fail',
+            summary: 'Project-local .npmrc exists and must not be present for release readiness.',
+            evidence: '.npmrc',
+        };
+    }
+    return {
+        id: 'npmrc-secret-boundary',
+        status: npmrcIgnored ? 'pass' : 'warn',
+        summary: npmrcIgnored ? '.npmrc is absent and ignored.' : '.npmrc is absent but not explicitly ignored.',
+        evidence: npmrcIgnored ? undefined : '.gitignore',
+    };
+}
+async function evaluatePackageSecurity(projectRoot) {
+    const report = await evaluatePackageSecurityGates(projectRoot);
+    const issues = [
+        ...report.package_allowlist.issues,
+        ...report.secret_scan.issues,
+    ];
+    return {
+        id: 'package-security-gates',
+        status: report.status === 'pass' ? 'pass' : 'fail',
+        summary: report.status === 'pass'
+            ? 'Package allowlist and high-confidence secret scan passed.'
+            : 'Package allowlist or high-confidence secret scan failed.',
+        evidence: issues.length > 0
+            ? issues.map((issue) => `${issue.code}:${issue.path}`).join(', ')
+            : `${report.package_allowlist.allowed_files.length} package entries; ${report.secret_scan.scanned_files} files scanned`,
+    };
+}
+async function evaluateSchemaArtifacts(projectRoot) {
+    const missing = REQUIRED_SCHEMA_FILES.filter((fileName) => !existsSync(path.join(projectRoot, 'schemas', 'sdd', fileName)));
+    return {
+        id: 'schema-artifacts',
+        status: missing.length === 0 ? 'pass' : 'fail',
+        summary: missing.length === 0 ? 'Required SDD schema artifacts are present.' : 'Required SDD schema artifacts are missing.',
+        evidence: missing.join(', ') || REQUIRED_SCHEMA_FILES.join(', '),
+    };
+}
+async function evaluateProvenanceAndSbom(projectRoot, packageJson) {
+    const workflowPath = path.join(projectRoot, '.github', 'workflows', 'release-prepare.yml');
+    const releaseDocPath = path.join(projectRoot, 'docs', 'release.md');
+    const securityDocPath = path.join(projectRoot, 'docs', 'security.md');
+    const workflow = await fs.readFile(workflowPath, 'utf-8').catch(() => '');
+    const releaseDoc = await fs.readFile(releaseDocPath, 'utf-8').catch(() => '');
+    const securityDoc = await fs.readFile(securityDocPath, 'utf-8').catch(() => '');
+    const docText = `${releaseDoc}\n${securityDoc}`;
+    const missing = [];
+    if (packageJson.publishConfig?.provenance !== true) {
+        missing.push('publishConfig.provenance=true');
+    }
+    if (!packageJson.scripts?.['release:sbom']) {
+        missing.push('scripts.release:sbom');
+    }
+    if (!/id-token:\s*write/u.test(workflow)) {
+        missing.push('release workflow id-token: write');
+    }
+    if (!/changesets\/action|npm\s+publish/u.test(workflow)) {
+        missing.push('release workflow publish step');
+    }
+    if (!/SBOM|Software Bill of Materials|npm sbom|CycloneDX|SPDX/iu.test(docText)) {
+        missing.push('SBOM documentation');
+    }
+    if (!/trusted publishing|OIDC|provenance/iu.test(docText)) {
+        missing.push('trusted publishing/provenance documentation');
+    }
+    return {
+        id: 'provenance-sbom',
+        status: missing.length === 0 ? 'pass' : 'fail',
+        summary: missing.length === 0
+            ? 'Trusted publishing provenance and SBOM evidence are configured.'
+            : 'Trusted publishing provenance or SBOM evidence is incomplete.',
+        evidence: missing.join(', ') || 'publishConfig.provenance, release:sbom, OIDC workflow, docs/release.md, docs/security.md',
+    };
+}
+async function evaluateTarballSmokeAndRollback(projectRoot, packageJson) {
+    const workflowPath = path.join(projectRoot, '.github', 'workflows', 'ci.yml');
+    const releaseDocPath = path.join(projectRoot, 'docs', 'release.md');
+    const workflow = await fs.readFile(workflowPath, 'utf-8').catch(() => '');
+    const releaseDoc = await fs.readFile(releaseDocPath, 'utf-8').catch(() => '');
+    const missing = [];
+    if (!packageJson.scripts?.['check:pack-version']) {
+        missing.push('scripts.check:pack-version');
+    }
+    if (!/pnpm\s+run\s+check:pack-version/u.test(workflow)) {
+        missing.push('CI check:pack-version step');
+    }
+    if (!/(npm|pnpm)\s+pack/u.test(workflow)) {
+        missing.push('CI tarball pack step');
+    }
+    if (!/npm\s+install\s+-g\s+\.\/.*--force/u.test(workflow.replace(/\s+/gu, ' '))) {
+        missing.push('CI global tarball install step');
+    }
+    if (!/codesdd\s+--version/u.test(workflow)) {
+        missing.push('CI CLI version smoke');
+    }
+    if (!/codesdd\s+install\s+--tools\s+none/u.test(workflow)) {
+        missing.push('CI bootstrap install smoke');
+    }
+    if (!/(manual fallback release|tarball)/iu.test(releaseDoc)) {
+        missing.push('tarball fallback release docs');
+    }
+    if (!/npm\s+deprecate\s+@devtrack-solution\/codesdd@<broken-version>/u.test(releaseDoc)) {
+        missing.push('npm deprecate rollback command');
+    }
+    if (!/(rollback strategy|cut a patch release|publish and update release notes)/iu.test(releaseDoc)) {
+        missing.push('rollback operator steps');
+    }
+    return {
+        id: 'tarball-smoke-rollback',
+        status: missing.length === 0 ? 'pass' : 'fail',
+        summary: missing.length === 0
+            ? 'Tarball install smoke and rollback evidence are configured.'
+            : 'Tarball install smoke or rollback evidence is incomplete.',
+        evidence: missing.join(', ') || '.github/workflows/ci.yml, docs/release.md, scripts.check:pack-version',
+    };
+}
+async function evaluateReleaseDocs(projectRoot) {
+    const required = ['docs/release.md', 'docs/security.md', 'README.md'];
+    const missing = required.filter((relativePath) => !existsSync(path.join(projectRoot, relativePath)));
+    return {
+        id: 'release-docs',
+        status: missing.length === 0 ? 'pass' : 'fail',
+        summary: missing.length === 0 ? 'Release and security documentation are present.' : 'Release or security documentation is missing.',
+        evidence: missing.join(', ') || required.join(', '),
+    };
+}
+//# sourceMappingURL=release-readiness.js.map

package/dist/core/sdd/runtime-boundary-contract.d.ts

@@ -0,0 +1,45 @@
+export declare const PROJECT_STATE_DIR_NAME = ".sdd";
+export declare const FORBIDDEN_PROJECT_RUNTIME_DIR_NAME = ".codesdd";
+export type CodesddStorageBoundary = 'project-state' | 'global-config' | 'global-cache' | 'global-runtime' | 'legacy-read-fallback' | 'invalid-project-runtime' | 'external';
+export interface CodesddStorageBoundaryClassification {
+    boundary: CodesddStorageBoundary;
+    path: string;
+    valid: boolean;
+    canonical: boolean;
+    versioned: boolean;
+    cacheable: boolean;
+    reason: string;
+}
+export interface CodesddStorageBoundaryReport {
+    schema_version: 1;
+    project_root: string;
+    project_state_dir: string;
+    global_runtime_dir: string;
+    global_config_path: string;
+    global_cache_dir: string;
+    global_cache_tiers: Record<string, string>;
+    legacy_config_path: string;
+    rules: {
+        versioned_project_state: string;
+        global_runtime: string;
+        global_cache: string;
+        forbidden_project_runtime: string;
+    };
+}
+export interface CodesddStorageBoundaryValidation {
+    valid: boolean;
+    findings: Array<{
+        path: string;
+        boundary: CodesddStorageBoundary;
+        message: string;
+    }>;
+    classifications: CodesddStorageBoundaryClassification[];
+}
+export declare function buildCodesddStorageBoundaryReport(projectRoot?: string): CodesddStorageBoundaryReport;
+export declare function classifyCodesddStoragePath(targetPath: string, options?: {
+    projectRoot?: string;
+}): CodesddStorageBoundaryClassification;
+export declare function validateCodesddStoragePaths(targetPaths: string[], options?: {
+    projectRoot?: string;
+}): CodesddStorageBoundaryValidation;
+//# sourceMappingURL=runtime-boundary-contract.d.ts.map

package/dist/core/sdd/runtime-boundary-contract.js

@@ -0,0 +1,90 @@
+import * as path from 'node:path';
+import { getGlobalCacheDir, getGlobalCacheTierDirs, getGlobalConfigDir, getGlobalConfigPath, getLegacyGlobalConfigDir, getLegacyGlobalConfigPath, } from '../global-config.js';
+export const PROJECT_STATE_DIR_NAME = '.sdd';
+export const FORBIDDEN_PROJECT_RUNTIME_DIR_NAME = '.codesdd';
+export function buildCodesddStorageBoundaryReport(projectRoot = process.cwd()) {
+    const normalizedProjectRoot = normalizePath(projectRoot);
+    return {
+        schema_version: 1,
+        project_root: normalizedProjectRoot,
+        project_state_dir: path.join(normalizedProjectRoot, PROJECT_STATE_DIR_NAME),
+        global_runtime_dir: getGlobalConfigDir(),
+        global_config_path: getGlobalConfigPath(),
+        global_cache_dir: getGlobalCacheDir(),
+        global_cache_tiers: getGlobalCacheTierDirs(),
+        legacy_config_path: getLegacyGlobalConfigPath(),
+        rules: {
+            versioned_project_state: 'Project decisions, backlog state, active/planned/archived features, ADRs, and docs live under .sdd and are versioned with the repository.',
+            global_runtime: 'Machine-level config, shell integration, provider settings, and reusable runtime files live under ~/.codesdd and are not repository state.',
+            global_cache: 'Cacheable derived data lives under ~/.codesdd/cache with project fingerprint isolation and can be discarded.',
+            forbidden_project_runtime: 'A project-local .codesdd directory is not canonical; use .sdd for project state and ~/.codesdd for runtime/cache.',
+        },
+    };
+}
+export function classifyCodesddStoragePath(targetPath, options = {}) {
+    const normalizedPath = normalizePath(targetPath);
+    const projectRoot = normalizePath(options.projectRoot ?? process.cwd());
+    const projectStateDir = path.join(projectRoot, PROJECT_STATE_DIR_NAME);
+    const forbiddenProjectRuntimeDir = path.join(projectRoot, FORBIDDEN_PROJECT_RUNTIME_DIR_NAME);
+    const globalConfigPath = normalizePath(getGlobalConfigPath());
+    const globalConfigDir = normalizePath(getGlobalConfigDir());
+    const globalCacheDir = normalizePath(getGlobalCacheDir());
+    const legacyConfigPath = normalizePath(getLegacyGlobalConfigPath());
+    const legacyConfigDir = normalizePath(getLegacyGlobalConfigDir());
+    if (isSameOrInside(normalizedPath, forbiddenProjectRuntimeDir)) {
+        return classification('invalid-project-runtime', normalizedPath, false, false, false, false, 'Project-local .codesdd is not canonical; use .sdd for project state or ~/.codesdd for runtime/cache.');
+    }
+    if (isSameOrInside(normalizedPath, projectStateDir)) {
+        return classification('project-state', normalizedPath, true, true, true, false, 'Versioned project governance, docs, decisions, and lifecycle state belong under .sdd.');
+    }
+    if (normalizedPath === globalConfigPath) {
+        return classification('global-config', normalizedPath, true, true, false, false, 'Machine-level CodeSDD configuration belongs in ~/.codesdd/config.toml and is not project state.');
+    }
+    if (isSameOrInside(normalizedPath, globalCacheDir)) {
+        return classification('global-cache', normalizedPath, true, true, false, true, 'Cacheable derived data belongs under ~/.codesdd/cache and must remain discardable.');
+    }
+    if (isSameOrInside(normalizedPath, globalConfigDir)) {
+        return classification('global-runtime', normalizedPath, true, true, false, false, 'Reusable machine runtime files belong under ~/.codesdd and are not repository state.');
+    }
+    if (normalizedPath === legacyConfigPath || isSameOrInside(normalizedPath, legacyConfigDir)) {
+        return classification('legacy-read-fallback', normalizedPath, true, false, false, false, 'Legacy global config is read only as a compatibility fallback; new runtime state belongs under ~/.codesdd.');
+    }
+    return classification('external', normalizedPath, true, false, false, false, 'Path is outside CodeSDD project state and global runtime boundaries.');
+}
+export function validateCodesddStoragePaths(targetPaths, options = {}) {
+    const classifications = targetPaths.map((targetPath) => classifyCodesddStoragePath(targetPath, options));
+    const findings = classifications
+        .filter((entry) => !entry.valid)
+        .map((entry) => ({
+        path: entry.path,
+        boundary: entry.boundary,
+        message: entry.reason,
+    }));
+    return {
+        valid: findings.length === 0,
+        findings,
+        classifications,
+    };
+}
+function classification(boundary, targetPath, valid, canonical, versioned, cacheable, reason) {
+    return {
+        boundary,
+        path: targetPath,
+        valid,
+        canonical,
+        versioned,
+        cacheable,
+        reason,
+    };
+}
+function normalizePath(input) {
+    return path.resolve(input);
+}
+function isSameOrInside(candidate, parent) {
+    if (candidate === parent) {
+        return true;
+    }
+    const relative = path.relative(parent, candidate);
+    return relative.length > 0 && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+//# sourceMappingURL=runtime-boundary-contract.js.map