sdd-agent-platform 0.3.0 → 0.4.0

package/packages/core/dist/artifacts/sdd-result.js

@@ -0,0 +1,198 @@
+import { SDD_RESULT_CONTRACT, SDD_RESULT_VERSION } from '../contracts.js';
+import { readArtifact } from '../run-state/artifacts.js';
+import { toArtifactRootRelativePath } from '../runtime-paths.js';
+import { validateArtifactTrust } from './sdd-evidence.js';
+export async function validateSddResultArtifact(projectRoot, runId, runRelativeArtifactPath, options = {}) {
+    const issues = [];
+    let artifactRootRelativePath;
+    try {
+        artifactRootRelativePath = toArtifactRootRelativePath(runRelativeArtifactPath);
+    }
+    catch (error) {
+        return { valid: false, result: null, issues: [contractIssue('artifacts', messageFromError(error), 'Use a run-relative artifacts/<file> path; the physical file lives under branch evidence .sdd/runs/<branchSlug>/evidence/artifacts/<file>. Source/test files belong in ## Evidence, not in sdd-result.artifacts.')] };
+    }
+    let raw;
+    try {
+        raw = await readArtifact(projectRoot, runId, artifactRootRelativePath);
+    }
+    catch (error) {
+        return { valid: false, result: null, issues: [contractIssue('artifacts', `Cannot read artifact ${runRelativeArtifactPath}: ${messageFromError(error)}`, `Create the expected artifact in branch evidence and pass the run-relative path ${runRelativeArtifactPath}.`)] };
+    }
+    if (raw.trim().length === 0) {
+        issues.push(contractIssue('artifacts', `Artifact ${runRelativeArtifactPath} is empty.`, 'Write non-empty evidence and an sdd-result block.'));
+    }
+    const parsed = parseSddResultMarkdown(raw);
+    issues.push(...parsed.issues);
+    let trust;
+    if (parsed.result) {
+        issues.push(...validateSddResult(parsed.result, { ...options, runRelativeArtifactPath }));
+        trust = validateArtifactTrust(raw, parsed.result, runRelativeArtifactPath, options);
+        if (!trust.valid) {
+            issues.push(...trust.issues);
+        }
+    }
+    return { valid: issues.length === 0 && parsed.result !== null, result: parsed.result, issues, trust };
+}
+export function parseSddResultMarkdown(raw) {
+    const matches = Array.from(raw.matchAll(/^\s*```sdd-result\s*\r?\n([\s\S]*?)\r?^\s*```\s*$/gm));
+    if (matches.length !== 1) {
+        return {
+            valid: false,
+            result: null,
+            issues: [contractIssue('sdd-result', matches.length === 0 ? 'No sdd-result fenced block found.' : `Expected exactly one sdd-result fenced block, found ${matches.length}.`, 'Embed one machine-readable sdd-result block in the artifact.')]
+        };
+    }
+    const metadata = parseSimpleYamlBlock(matches[0][1] ?? '');
+    const result = buildSddResult(metadata);
+    const issues = result ? validateSddResult(result) : validateSddResultMetadata(metadata);
+    return { valid: issues.length === 0 && result !== null, result, issues };
+}
+export function validateSddResult(result, options = {}) {
+    const issues = validateSddResultMetadata(result.rawMetadata);
+    if (options.expectedTask && result.task !== options.expectedTask) {
+        issues.push(contractIssue('task', `sdd-result task ${result.task} does not match expected task ${options.expectedTask}.`, 'Write the delegated task id into the sdd-result task field.'));
+    }
+    if (options.expectedAgent && result.agent !== options.expectedAgent) {
+        issues.push(contractIssue('agent', `sdd-result agent ${result.agent} does not match expected agent ${options.expectedAgent}.`, 'Write the delegated agent name into the sdd-result agent field.'));
+    }
+    if (options.runRelativeArtifactPath && !result.artifacts.includes(options.runRelativeArtifactPath)) {
+        issues.push(contractIssue('artifacts', `sdd-result artifacts does not include its own path ${options.runRelativeArtifactPath}.`, `Add the current artifact path exactly: ${options.runRelativeArtifactPath}.`));
+    }
+    return issues;
+}
+export function isSddResultStatus(value) {
+    return value === 'PASS' || value === 'PASS_WITH_GAPS' || value === 'FAIL' || value === 'BLOCKED' || value === 'TIMED_OUT' || value === 'CANCELLED';
+}
+function buildSddResult(metadata) {
+    const contract = scalarValue(metadata.contract);
+    const version = scalarValue(metadata.version);
+    const agent = scalarValue(metadata.agent);
+    const task = scalarValue(metadata.task);
+    const status = scalarValue(metadata.status);
+    const artifacts = listValue(metadata.artifacts);
+    if (contract !== SDD_RESULT_CONTRACT || version !== SDD_RESULT_VERSION || !agent || !task || !isSddResultStatus(status) || artifacts.length === 0) {
+        return null;
+    }
+    return {
+        contract: SDD_RESULT_CONTRACT,
+        version: SDD_RESULT_VERSION,
+        agent,
+        task,
+        status,
+        artifacts,
+        rawMetadata: metadata
+    };
+}
+function validateSddResultMetadata(metadata) {
+    const issues = [];
+    const contract = scalarValue(metadata.contract);
+    const version = scalarValue(metadata.version);
+    const agent = scalarValue(metadata.agent);
+    const task = scalarValue(metadata.task);
+    const status = scalarValue(metadata.status);
+    const artifacts = listValue(metadata.artifacts);
+    if (contract !== SDD_RESULT_CONTRACT) {
+        issues.push(contractIssue('contract', `Expected ${SDD_RESULT_CONTRACT}, got ${contract ?? 'missing'}.`, 'Use contract: sdd-result-v1.'));
+    }
+    if (version !== SDD_RESULT_VERSION) {
+        issues.push(contractIssue('version', `Expected ${SDD_RESULT_VERSION}, got ${version ?? 'missing'}.`, 'Use version: 1.3.0 until a new contract version is introduced.'));
+    }
+    if (!agent) {
+        issues.push(contractIssue('agent', 'sdd-result agent is required.', 'Set agent to the producing agent name.'));
+    }
+    if (!task) {
+        issues.push(contractIssue('task', 'sdd-result task is required.', 'Set task to the delegated task id.'));
+    }
+    if (!isSddResultStatus(status)) {
+        issues.push(contractIssue('status', `Unsupported sdd-result status ${status ?? 'missing'}.`, 'Use PASS, PASS_WITH_GAPS, FAIL, BLOCKED, TIMED_OUT, or CANCELLED.'));
+    }
+    if (artifacts.length === 0) {
+        issues.push(contractIssue('artifacts', 'sdd-result artifacts must contain at least one path.', 'Add the current run-relative artifact path, for example artifacts/<file>. Source/test files belong in ## Evidence.'));
+    }
+    for (const artifactPath of artifacts) {
+        validateRunRelativeArtifactReference(artifactPath, issues);
+        if (!artifactPath.replace(/\\/g, '/').startsWith('artifacts/')) {
+            issues.push(contractIssue('artifacts', `Source/test path ${artifactPath} is not a run artifact reference.`, 'Move source/test file citations to ## Evidence; keep only run-relative artifacts/<file> paths in sdd-result.artifacts.'));
+        }
+    }
+    return issues;
+}
+function validateRunRelativeArtifactReference(value, issues, field = 'artifacts') {
+    try {
+        toArtifactRootRelativePath(value);
+    }
+    catch (error) {
+        issues.push(contractIssue(field, messageFromError(error), 'Use a run-relative artifacts/<file> path inside the active run.'));
+    }
+}
+function contractIssue(field, message, recommendation) {
+    return { field, message, recommendation };
+}
+function messageFromError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function parseSimpleYamlBlock(raw) {
+    const result = {};
+    const lines = raw.split(/\r?\n/);
+    let currentListKey = null;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+        }
+        if (currentListKey && /^-\s+/.test(trimmed)) {
+            const current = result[currentListKey];
+            const items = Array.isArray(current) ? current : [];
+            items.push(unquoteSimpleYamlValue(trimmed.slice(2).trim()));
+            result[currentListKey] = items;
+            continue;
+        }
+        const scalarMatch = trimmed.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (!scalarMatch) {
+            currentListKey = null;
+            continue;
+        }
+        const key = scalarMatch[1];
+        const value = scalarMatch[2].trim();
+        if (value === '') {
+            result[key] = [];
+            currentListKey = key;
+        }
+        else if (value === '[]') {
+            result[key] = [];
+            currentListKey = null;
+        }
+        else if (value.startsWith('[') && value.endsWith(']')) {
+            result[key] = value.slice(1, -1).split(',').map((item) => unquoteSimpleYamlValue(item.trim())).filter(Boolean);
+            currentListKey = null;
+        }
+        else {
+            result[key] = unquoteSimpleYamlValue(value);
+            currentListKey = null;
+        }
+    }
+    return result;
+}
+function unquoteSimpleYamlValue(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+function scalarValue(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function listValue(value) {
+    if (Array.isArray(value)) {
+        return value.filter(Boolean);
+    }
+    if (!value || value === '[]') {
+        return [];
+    }
+    return [value];
+}
+//# sourceMappingURL=sdd-result.js.map

package/packages/core/dist/artifacts/sdd-result.js.map

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

package/packages/core/dist/artifacts/templates.d.ts

@@ -0,0 +1,10 @@
+import type { SddResultStatus } from './sdd-result.js';
+export interface SddResultArtifactTemplateOptions {
+    branch?: string;
+    runId?: string;
+    taskId: string;
+    agent: string;
+    artifactPath: string;
+    status?: SddResultStatus;
+}
+export declare function renderSddResultArtifactTemplate(projectRoot: string, options: SddResultArtifactTemplateOptions): Promise<string>;

package/packages/core/dist/artifacts/templates.js

@@ -0,0 +1,79 @@
+import { SDD_RESULT_CONTRACT, SDD_RESULT_VERSION } from '../contracts.js';
+import { getRunRelativeArtifactPath, toArtifactRootRelativePath } from '../runtime-paths.js';
+import { readRunState } from '../run-state/run-state.js';
+import { resolveSddContext } from '../sdd-docs/context.js';
+import { parseSddBranch } from '../sdd-docs/task-parser.js';
+import { inspectSddTask } from '../sdd-docs/task-inspection.js';
+import { isSddResultStatus } from './sdd-result.js';
+export async function renderSddResultArtifactTemplate(projectRoot, options) {
+    const runState = options.runId ? await readRunState(projectRoot, options.runId).catch(() => null) : null;
+    const branch = options.branch ?? runState?.partition ?? runState?.gitBranch ?? (await resolveSddContext(projectRoot)).branch;
+    const status = options.status ?? 'PASS';
+    if (!isSddResultStatus(status)) {
+        throw new Error(`Unsupported sdd-result status ${status}.`);
+    }
+    const artifactRootRelativePath = toArtifactRootRelativePath(options.artifactPath);
+    const runRelativeArtifactPath = getRunRelativeArtifactPath(artifactRootRelativePath);
+    const lines = [
+        `# ${options.agent} result`,
+        '',
+        '```sdd-result',
+        `contract: ${SDD_RESULT_CONTRACT}`,
+        `version: ${SDD_RESULT_VERSION}`,
+        `agent: ${options.agent}`,
+        `task: ${options.taskId}`,
+        `status: ${status}`,
+        'artifacts:',
+        `  - ${runRelativeArtifactPath}`,
+        '```',
+        ''
+    ];
+    let warning = null;
+    let task = null;
+    try {
+        const model = await parseSddBranch(projectRoot, branch);
+        const inspected = inspectSddTask(model, options.taskId);
+        task = inspected.task;
+        if (!task) {
+            warning = `Task ${options.taskId} was not found in specs/${branch}/tasks.md.`;
+        }
+    }
+    catch (error) {
+        warning = `Could not inspect task ${options.taskId} on branch ${branch}: ${messageFromError(error)}`;
+    }
+    if (warning) {
+        lines.push('## Warning', '', `- ${warning}`, '');
+    }
+    if (options.agent === 'validator' && task) {
+        lines.push('## Acceptance Mapping', '');
+        const targets = taskAcceptanceCoverageTargets(task);
+        lines.push(...(targets.length > 0
+            ? targets.map((target) => `- Acceptance ${target.label}: TODO. Add validation evidence${target.description ? ` for ${target.description}` : ''}.`)
+            : ['- No Acceptance items are declared for this task.']));
+        lines.push('', '## Evidence', '');
+        lines.push(...(task.validation.length > 0
+            ? task.validation.map((command) => `- TODO run validation command: ${command}`)
+            : ['- TODO add validation evidence.']));
+        lines.push('');
+    }
+    else {
+        lines.push('## Evidence', '', `- TODO cite files, commands, and task ${options.taskId} evidence here.`, '');
+    }
+    return lines.join('\n');
+}
+function taskAcceptanceCoverageTargets(task) {
+    if (task.acceptanceRefs.length > 0) {
+        return task.acceptanceRefs.map((ref, index) => ({
+            label: ref,
+            description: task.acceptance[index] ?? null
+        }));
+    }
+    return task.acceptance.map((acceptance) => ({
+        label: acceptance,
+        description: null
+    }));
+}
+function messageFromError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=templates.js.map

package/packages/core/dist/artifacts/templates.js.map

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

package/packages/core/dist/artifacts.d.ts

@@ -0,0 +1,4 @@
+export * from './artifacts/ingestion.js';
+export * from './artifacts/sdd-evidence.js';
+export * from './artifacts/sdd-result.js';
+export * from './artifacts/templates.js';

package/packages/core/dist/artifacts.js

@@ -0,0 +1,5 @@
+export * from './artifacts/ingestion.js';
+export * from './artifacts/sdd-evidence.js';
+export * from './artifacts/sdd-result.js';
+export * from './artifacts/templates.js';
+//# sourceMappingURL=artifacts.js.map

package/packages/core/dist/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC"}

package/packages/core/dist/coding-facts/contracts.d.ts

@@ -0,0 +1,71 @@
+import type { RuntimeConfidence, RuntimeRef, RuntimeScope } from '../contracts.js';
+import { CODING_FACT_SET_CONTRACT_VERSION } from '../contracts.js';
+export type CodingFactKind = 'document' | 'task' | 'file' | 'test' | 'runtime' | 'evidence' | 'external';
+export type CodingFileFactClass = 'spec-doc' | 'runtime-state' | 'cli-source' | 'core-source' | 'test-source' | 'generated-ai-entry' | 'release-doc' | 'unknown';
+export interface CodingFact<TValue = unknown> {
+    id: string;
+    kind: CodingFactKind;
+    source: string;
+    scope: RuntimeScope;
+    confidence: RuntimeConfidence;
+    observedAt: string;
+    inputHash?: string;
+    refs: RuntimeRef[];
+    reasons: string[];
+    value: TValue;
+}
+export interface CodingFileFact {
+    path: string;
+    fileClass: CodingFileFactClass;
+    changed: boolean;
+    publicApi: boolean;
+    generated: boolean;
+    reasons: string[];
+}
+export interface CodingTestFact {
+    command: string;
+    acceptanceRefs: string[];
+    required: boolean;
+    sourceRefs: RuntimeRef[];
+}
+export interface CodingRuntimeFact {
+    name: string;
+    status: 'present' | 'missing' | 'stale' | 'failed' | 'unknown';
+    refs: RuntimeRef[];
+    reasons: string[];
+}
+export interface CodingEvidenceFact {
+    acceptanceRef: string;
+    evidenceRefs: RuntimeRef[];
+    status: 'present' | 'missing' | 'stale' | 'failed';
+    reasons: string[];
+}
+export interface CodingExternalFact {
+    name: string;
+    known: boolean;
+    confidence: RuntimeConfidence;
+    refs: RuntimeRef[];
+    reasons: string[];
+}
+export interface CodingFactSet {
+    contract: typeof CODING_FACT_SET_CONTRACT_VERSION;
+    scope: RuntimeScope;
+    request: {
+        intentKnown: boolean;
+        acceptanceKnown: boolean;
+        validationKnown: boolean;
+    };
+    documents: {
+        specExists: boolean;
+        planExists: boolean;
+        tasksExists: boolean;
+        verifiesExists: boolean;
+    };
+    facts: CodingFact[];
+    files: CodingFileFact[];
+    tests: CodingTestFact[];
+    runtime: CodingRuntimeFact[];
+    evidence: CodingEvidenceFact[];
+    external: CodingExternalFact[];
+    generatedAt: string;
+}

package/packages/core/dist/coding-facts/contracts.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contracts.js.map

package/packages/core/dist/coding-facts/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","sourceRoot":"","sources":["../../src/coding-facts/contracts.ts"],"names":[],"mappings":""}

package/packages/core/dist/coding-facts.d.ts

@@ -0,0 +1 @@
+export * from './coding-facts/contracts.js';

package/packages/core/dist/coding-facts.js

@@ -0,0 +1,2 @@
+export * from './coding-facts/contracts.js';
+//# sourceMappingURL=coding-facts.js.map

package/packages/core/dist/coding-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coding-facts.js","sourceRoot":"","sources":["../src/coding-facts.ts"],"names":[],"mappings":"AAAA,cAAc,6BAA6B,CAAC"}

package/packages/core/dist/config/init-project.d.ts

@@ -0,0 +1,31 @@
+import { type AiProjectionResult, type AiToolSelection } from '../ai-tools.js';
+export type InitDocumentStatus = 'created' | 'unchanged' | 'overwritten' | 'skipped';
+export interface InitDocumentReport {
+    branch: string;
+    relativePath: string;
+    status: InitDocumentStatus;
+    message: string;
+}
+export interface InitDocumentsResult {
+    branch: string;
+    root: string;
+    documents: InitDocumentReport[];
+}
+export interface InitProjectResult {
+    configPath: string;
+    created: boolean;
+    documents: InitDocumentsResult;
+    aiTools: AiProjectionResult[];
+}
+export declare function applyInitDocuments(projectRoot: string, options: {
+    branch: string;
+    force?: boolean;
+    scaffoldDocuments: boolean;
+    docsLanguage: string;
+}): Promise<InitDocumentsResult>;
+export declare function initProject(projectRoot: string, options?: {
+    force?: boolean;
+    aiTool?: AiToolSelection;
+    branch?: string;
+    scaffoldDocuments?: boolean;
+}): Promise<InitProjectResult>;

package/packages/core/dist/config/init-project.js

@@ -0,0 +1,88 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { applyAiToolEntries } from '../ai-tools.js';
+import { getProjectConfigPath, getRunsDir, getSddDir } from '../runtime-paths.js';
+import { detectProjectConfig, readProjectConfig, renderProjectConfig } from './project-config.js';
+import { assertSafePathSegment } from '../path-safety.js';
+import { exists } from '../storage/json-io.js';
+import { renderInitPlanDocument, renderInitSpecDocument, renderInitTasksDocument, renderInitVerifyDocument } from './starter-documents.js';
+export async function applyInitDocuments(projectRoot, options) {
+    assertSafePathSegment(options.branch, 'branch');
+    const docsRoot = path.join(projectRoot, 'specs', options.branch);
+    const now = new Date().toISOString();
+    const documents = [
+        { name: 'spec.md', content: renderInitSpecDocument(options.branch, now, options.docsLanguage) },
+        { name: 'plan.md', content: renderInitPlanDocument(options.branch, now, options.docsLanguage) },
+        { name: 'tasks.md', content: renderInitTasksDocument(options.branch, now, options.docsLanguage) },
+        { name: 'verify.md', content: renderInitVerifyDocument(options.branch, now, options.docsLanguage) }
+    ];
+    if (!options.scaffoldDocuments) {
+        return {
+            branch: options.branch,
+            root: path.relative(projectRoot, docsRoot),
+            documents: documents.map((document) => ({
+                branch: options.branch,
+                relativePath: `specs/${options.branch}/${document.name}`,
+                status: 'skipped',
+                message: 'Starter semantic document scaffold skipped.'
+            }))
+        };
+    }
+    await mkdir(docsRoot, { recursive: true });
+    const reports = [];
+    for (const document of documents) {
+        const absolutePath = path.join(docsRoot, document.name);
+        const relativePath = `specs/${options.branch}/${document.name}`;
+        const existed = await exists(absolutePath);
+        if (existed && !options.force) {
+            reports.push({
+                branch: options.branch,
+                relativePath,
+                status: 'unchanged',
+                message: 'Existing semantic document preserved.'
+            });
+            continue;
+        }
+        await writeFile(absolutePath, document.content, 'utf8');
+        reports.push({
+            branch: options.branch,
+            relativePath,
+            status: existed ? 'overwritten' : 'created',
+            message: existed ? 'Starter semantic document overwritten by explicit force.' : 'Starter semantic document created.'
+        });
+    }
+    return { branch: options.branch, root: path.relative(projectRoot, docsRoot), documents: reports };
+}
+export async function initProject(projectRoot, options = {}) {
+    const sddDir = getSddDir(projectRoot);
+    const runsDir = getRunsDir(projectRoot);
+    const configPath = getProjectConfigPath(projectRoot);
+    const requestedBranch = options.branch?.trim();
+    const scaffoldDocuments = options.scaffoldDocuments ?? true;
+    const branch = requestedBranch || 'master';
+    assertSafePathSegment(branch, 'branch');
+    await mkdir(runsDir, { recursive: true });
+    let created = false;
+    let projectConfig = null;
+    if (options.force || !await exists(configPath)) {
+        const projectName = path.basename(path.resolve(projectRoot));
+        const config = await detectProjectConfig(projectRoot, projectName);
+        config.sdd.default_branch = requestedBranch || (scaffoldDocuments ? branch : undefined);
+        await writeFile(configPath, renderProjectConfig(config), 'utf8');
+        projectConfig = config;
+        created = true;
+    }
+    if (!projectConfig) {
+        projectConfig = await readProjectConfig(projectRoot);
+    }
+    const documents = await applyInitDocuments(projectRoot, {
+        branch,
+        force: options.force,
+        scaffoldDocuments,
+        docsLanguage: projectConfig.sdd.docs_language
+    });
+    await mkdir(sddDir, { recursive: true });
+    const aiTools = await applyAiToolEntries(projectRoot, { tool: options.aiTool ?? 'auto' });
+    return { configPath, created, documents, aiTools };
+}
+//# sourceMappingURL=init-project.js.map

package/packages/core/dist/config/init-project.js.map

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

package/packages/core/dist/config/project-config.d.ts

@@ -0,0 +1,49 @@
+import { PROJECT_CONFIG_CONTRACT } from '../contracts.js';
+import type { DetectionConfidence } from './project-detection.js';
+export type ProjectLifecycleProfile = 'direct' | 'compact' | 'full' | 'research';
+export interface ProjectConfig<TAgentRuntimeConfig = unknown> {
+    contract: typeof PROJECT_CONFIG_CONTRACT;
+    project: {
+        name: string;
+        language: string;
+        framework: string;
+    };
+    detection?: {
+        confidence: DetectionConfidence;
+        mixed_stack: boolean;
+        primary: string;
+        candidates: Array<{
+            id: string;
+            confidence: DetectionConfidence;
+            score: number;
+        }>;
+    };
+    sdd: {
+        spec_dir: string;
+        default_branch?: string;
+        docs_language: string;
+        compatible_with: string;
+    };
+    validation: {
+        default: string[];
+    };
+    editing: {
+        prefer_hashline: boolean;
+        native_edit_fallback: boolean;
+    };
+    runtime: {
+        background_write: boolean;
+        worktree_isolation: boolean;
+        sync_back_mode: 'proposal';
+    };
+    lifecycle: {
+        decision_required: boolean;
+        profiles: ProjectLifecycleProfile[];
+    };
+    agentRuntime?: TAgentRuntimeConfig;
+}
+export declare function detectProjectConfig<TAgentRuntimeConfig = unknown>(projectRoot: string, projectName: string): Promise<ProjectConfig<TAgentRuntimeConfig>>;
+export declare function defaultProjectConfig<TAgentRuntimeConfig = unknown>(projectName: string): ProjectConfig<TAgentRuntimeConfig>;
+export declare function renderProjectConfig(config: ProjectConfig<unknown>): string;
+export declare function readProjectConfig<TAgentRuntimeConfig = unknown>(projectRoot: string, parseAgentRuntime?: (raw: string) => TAgentRuntimeConfig | undefined): Promise<ProjectConfig<TAgentRuntimeConfig>>;
+export declare function parseProjectConfig<TAgentRuntimeConfig = unknown>(raw: string, configPath: string, parseAgentRuntime?: (raw: string) => TAgentRuntimeConfig | undefined): ProjectConfig<TAgentRuntimeConfig>;