orizu 0.4.0 → 0.5.0

package/dist/workspace.js

@@ -1,76 +1,887 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
-import { join, resolve } from 'path';
+import { existsSync, lstatSync, mkdirSync, readlinkSync, readdirSync, readFileSync, renameSync, symlinkSync, unlinkSync, writeFileSync, } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
 export const WORKSPACE_DIR_NAME = '.orizu';
-const WORKSPACE_README = `# Orizu workspace
+export const WORKSPACE_SCHEMA_VERSION = 'orizu.workspace.v0';
+export const WORKSPACE_SETUP_VERSION = '0.1.0';
+export const WORKSPACE_ROOT_FILES = [
+    'README.md',
+    'orizu.team.json',
+    'AGENTS.md',
+    'CLAUDE.md',
+    'Memory.md',
+    '.gitignore',
+];
+export const WORKSPACE_ROOT_DIRS = [
+    WORKSPACE_DIR_NAME,
+    'source-repos',
+    'projects',
+    'sessions',
+];
+export const PROJECT_ROOT_FILES = [
+    'README.md',
+    'memory.md',
+    'orizu.project.json',
+    '.gitignore',
+];
+export const PROJECT_PRIMITIVE_DIRS = [
+    'datasets',
+    'apps',
+    'tasks',
+    'prompts',
+    'scorers',
+    'optimizations',
+];
+export const REPO_STATES = [
+    'source',
+    'draft',
+    'snapshot',
+    'mirror',
+    'cache',
+    'object_ref_only',
+];
+export const CANONICAL_OWNERS = [
+    'repo',
+    'orizu-db',
+    'object-storage',
+    'local',
+];
+function hasAllowedValue(values, value) {
+    return typeof value === 'string' && values.includes(value);
+}
+function normalizeSlug(value, fallback) {
+    const normalized = (value || fallback)
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return normalized || fallback;
+}
+function normalizeProjectSeeds(options) {
+    const explicitProjects = options?.projects?.length
+        ? options.projects
+        : [{ slug: options?.projectSlug || 'local-project', id: null, name: null }];
+    const bySlug = new Map();
+    for (const project of explicitProjects) {
+        const slug = normalizeSlug(project.slug, 'local-project');
+        if (!bySlug.has(slug)) {
+            bySlug.set(slug, {
+                slug,
+                id: project.id || null,
+                name: project.name || null,
+            });
+        }
+    }
+    return Array.from(bySlug.values());
+}
+function resolveWorkspaceRoot(options) {
+    return resolve(options?.workspaceRoot || options?.cwd || process.cwd());
+}
+export function getWorkspaceRoot(cwd) {
+    return resolve(cwd || process.cwd());
+}
+export function workspaceExists(cwd) {
+    return existsSync(join(getWorkspaceRoot(cwd), 'orizu.team.json'));
+}
+function formatJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function createTeamManifest(options) {
+    return formatJson({
+        schemaVersion: WORKSPACE_SCHEMA_VERSION,
+        kind: 'team',
+        slug: options.teamSlug,
+        teamId: options.teamId,
+        serviceOrigin: options.serviceOrigin,
+        defaultObjectStore: {
+            provider: 'supabase',
+            bucket: 'orizu-artifacts',
+        },
+        canonical: {
+            owner: 'repo',
+            repoState: 'source',
+            serviceId: options.attachWorkspaceId,
+            versionId: null,
+            contentSha256: null,
+            lastPulledAt: null,
+            objectRef: null,
+            notes: null,
+        },
+        setup: {
+            setupVersion: WORKSPACE_SETUP_VERSION,
+            createdBy: 'orizu setup',
+            createdAt: new Date().toISOString(),
+            cliVersion: options.cliVersion,
+            attachedWorkspaceId: options.attachWorkspaceId,
+        },
+    });
+}
+function createProjectManifest(teamSlug, project) {
+    return formatJson({
+        schemaVersion: WORKSPACE_SCHEMA_VERSION,
+        kind: 'project',
+        slug: project.slug,
+        name: project.name || null,
+        projectId: project.id || null,
+        teamSlug,
+        sourceRepos: [],
+        policies: {
+            defaultRepoState: 'draft',
+        },
+        canonical: {
+            owner: 'repo',
+            repoState: 'draft',
+            serviceId: null,
+            versionId: null,
+            contentSha256: null,
+            lastPulledAt: null,
+            objectRef: null,
+            notes: null,
+        },
+    });
+}
+function rootReadme(teamSlug) {
+    return `# ${teamSlug} Orizu workbench
 
-Local Orizu artifacts for this repository. This folder is gitignored by
-default: generated and server-derived content here is not guaranteed to stay
-in sync with the Orizu server, so checking it in would risk drift. Safe,
-user-authored configuration may move to a committed location once a sync model
-exists.
+This repository is the portable Orizu workbench for this team. Durable context,
+manifests, intentional snapshots, summaries, and promotion artifacts live in
+Git. Live product state remains in Orizu DB/storage unless a repo file is
+explicitly applied through Orizu.
 
-- \`workspace.json\`: safe local metadata (no secrets; credentials stay in
-  \`~/.config/orizu\`).
-- \`generated/\`: runner artifacts, exports, and other generated files.
+Generated exports, local caches, raw logs, raw transcripts, bulky datasets, and
+temporary runner materialization belong in ignored or object-backed locations.
 `;
-export function getWorkspaceRoot(cwd) {
-    return resolve(cwd || process.cwd(), WORKSPACE_DIR_NAME);
 }
-export function workspaceExists(cwd) {
-    return existsSync(join(getWorkspaceRoot(cwd), 'workspace.json'));
+function projectReadme(projectSlug) {
+    return `# ${projectSlug}
+
+Project-level Orizu context. Add human notes here and keep machine-readable
+state in the adjacent \`orizu.project.json\` manifest and primitive manifests.
+`;
+}
+const AGENTS_MD = `# Orizu Agent Instructions
+
+This is a team-level Orizu workbench. Use this file for durable, human-readable
+agent guidance; keep detailed CLI manuals in installed skills or reference
+docs instead of pasting them here.
+
+Before changing anything, read:
+
+- \`README.md\` for the team workbench overview.
+- \`Memory.md\` for durable team preferences and decisions.
+- \`projects/*/README.md\` and \`projects/*/memory.md\` for project context.
+- \`orizu.*.json\` manifests for machine-readable ids, ownership, source-of-truth
+  state, commands, and object refs.
+
+Use \`orizu --help\`, \`orizu <command> --help\`, and
+\`orizu capabilities --json\` to discover exact CLI behavior. Do not duplicate
+Orizu runtime behavior in repo scripts; go through the CLI.
+
+Treat Git-tracked files as source/context or explicit snapshots. Live Orizu
+state remains in Orizu DB/storage unless a manifest says a repo file is the
+source of truth. Treat \`.orizu/\`, raw logs, raw transcripts, bulky datasets,
+and local source checkouts as ignored cache or object-backed state unless
+explicitly promoted.
+
+Ask before creating Orizu server state or changing human-authored repo files.
+`;
+const MEMORY_MD = `# Orizu Memory
+
+Record durable team-level preferences, decisions, and lessons here.
+`;
+const PROJECT_MEMORY_MD = `# Project Memory
+
+Record durable project-level preferences, decisions, and lessons here.
+`;
+const CLAUDE_POINTER = `# Claude Instructions
+
+Read \`AGENTS.md\` in this directory for the canonical Orizu agent instructions.
+`;
+const OLD_CLAUDE_POINTER = `# Claude Instructions
+
+Read \`Agents.md\` in this directory for the canonical Orizu agent instructions.
+`;
+const ORIZU_CLI_AGENTS_START_MARKER = '<!-- orizu-cli:start -->';
+const ORIZU_CLI_AGENTS_END_MARKER = '<!-- orizu-cli:end -->';
+const LOCAL_WORKSPACE_README = `# Local Orizu cache
+
+This directory is ignored by default. Use it for generated exports, local
+caches, temporary runner materialization, and server-derived files that may
+drift. The durable workspace contract lives in the root and project manifests
+outside this directory.
+`;
+const ROOT_GITIGNORE_ENTRIES = [
+    '.orizu/',
+    '.logs/',
+    '**/raw_transcript/',
+    '**/*.raw.jsonl',
+    '**/*.log',
+    '**/log_dir/',
+    '**/downloaded-datasets/',
+    '**/trace-pulls/',
+    'source-repos/*/checkout/',
+    'source-repos/*/worktree/',
+    '.env',
+    '.env.*',
+    'node_modules/',
+    '.next/',
+    'dist/',
+    'build/',
+    '.venv/',
+    '__pycache__/',
+];
+const PROJECT_GITIGNORE_ENTRIES = [
+    '.orizu/',
+    '.logs/',
+    '**/raw_transcript/',
+    '**/*.raw.jsonl',
+    '**/*.log',
+    '**/log_dir/',
+    '**/downloaded-datasets/',
+    '**/trace-pulls/',
+    '.env',
+    '.env.*',
+    '.venv/',
+    '__pycache__/',
+];
+function operation(action, path, reason, extra) {
+    return {
+        action,
+        path,
+        reason,
+        safe: extra?.safe ?? true,
+        ...extra,
+    };
+}
+function lstatIfExists(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+function pathExists(path) {
+    return existsSync(path) || lstatIfExists(path) !== null;
+}
+function rootEntryCaseMatches(root, canonical) {
+    const matches = rootEntryNames(root).filter(name => name.toLowerCase() === canonical.toLowerCase());
+    return {
+        hasCanonical: matches.includes(canonical),
+        nonCanonical: matches.filter(name => name !== canonical),
+    };
+}
+function pushCreateDir(operations, path, reason) {
+    if (!pathExists(path)) {
+        operations.push(operation('create_dir', path, reason));
+    }
+}
+function pushCreateFile(operations, path, content, reason) {
+    if (!pathExists(path)) {
+        operations.push(operation('create_file', path, reason, { content }));
+    }
 }
-function ensureGitignoreEntry(cwd, dryRun) {
-    const gitignorePath = resolve(cwd, '.gitignore');
-    const entry = `${WORKSPACE_DIR_NAME}/`;
-    if (existsSync(gitignorePath)) {
-        const existing = readFileSync(gitignorePath, 'utf8');
-        const hasEntry = existing
-            .split('\n')
-            .some(line => line.trim() === entry || line.trim() === WORKSPACE_DIR_NAME);
-        if (hasEntry) {
-            return { updated: false, action: null };
+function pushCreateRootFile(operations, root, filename, content, reason) {
+    const { hasCanonical, nonCanonical } = rootEntryCaseMatches(root, filename);
+    if (!hasCanonical && nonCanonical.length === 0) {
+        operations.push(operation('create_file', join(root, filename), reason, { content }));
+    }
+}
+function pushCaseRename(operations, root, filename, fix) {
+    if (!fix) {
+        return;
+    }
+    const { hasCanonical, nonCanonical } = rootEntryCaseMatches(root, filename);
+    if (!hasCanonical && nonCanonical.length === 1) {
+        operations.push(operation('rename_file', join(root, filename), `rename ${nonCanonical[0]} to ${filename}`, {
+            sourcePath: join(root, nonCanonical[0]),
+        }));
+    }
+}
+function isKnownClaudePointer(path) {
+    try {
+        const trimmed = readFileSync(path, 'utf8').trim();
+        return trimmed === CLAUDE_POINTER.trim() ||
+            trimmed === OLD_CLAUDE_POINTER.trim();
+    }
+    catch {
+        return false;
+    }
+}
+function pushClaudeMigrationRepair(operations, root, sourceName, options) {
+    if (!options?.fix) {
+        return;
+    }
+    const sourcePath = join(root, sourceName);
+    const claudePath = join(root, 'CLAUDE.md');
+    let repairable = false;
+    try {
+        const stat = lstatSync(sourcePath);
+        repairable = stat.isSymbolicLink() || isKnownClaudePointer(sourcePath);
+    }
+    catch {
+        repairable = false;
+    }
+    if (!repairable) {
+        return;
+    }
+    operations.push(options.noSymlinks
+        ? operation('replace_file', claudePath, 'repair CLAUDE.md pointer file', { content: CLAUDE_POINTER })
+        : operation('replace_symlink', claudePath, 'repair CLAUDE.md symlink target', { target: 'AGENTS.md' }));
+}
+function pushExistingClaudeRepair(operations, root, options) {
+    if (!options?.fix) {
+        return;
+    }
+    const claudePath = join(root, 'CLAUDE.md');
+    if (!rootEntryCaseMatches(root, 'CLAUDE.md').hasCanonical) {
+        return;
+    }
+    try {
+        const stat = lstatSync(claudePath);
+        if (stat.isSymbolicLink()) {
+            const target = readlinkSync(claudePath);
+            if (options.noSymlinks) {
+                operations.push(operation('replace_file', claudePath, 'repair CLAUDE.md pointer file', { content: CLAUDE_POINTER }));
+            }
+            else if (target !== 'AGENTS.md') {
+                operations.push(operation('replace_symlink', claudePath, 'repair CLAUDE.md symlink target', { target: 'AGENTS.md' }));
+            }
+            return;
         }
-        if (!dryRun) {
-            const separator = existing.endsWith('\n') || existing.length === 0 ? '' : '\n';
-            writeFileSync(gitignorePath, `${existing}${separator}\n# Local Orizu workspace (generated; not synced with the server)\n${entry}\n`, 'utf8');
+        if (isKnownClaudePointer(claudePath)) {
+            operations.push(options.noSymlinks
+                ? operation('replace_file', claudePath, 'repair CLAUDE.md pointer file', { content: CLAUDE_POINTER })
+                : operation('replace_symlink', claudePath, 'repair CLAUDE.md symlink target', { target: 'AGENTS.md' }));
         }
-        return { updated: true, action: `append ${entry} to .gitignore` };
     }
-    if (!dryRun) {
-        writeFileSync(gitignorePath, `# Local Orizu workspace (generated; not synced with the server)\n${entry}\n`, 'utf8');
+    catch {
+        // Validation will report unreadable or missing files.
     }
-    return { updated: true, action: `create .gitignore with ${entry}` };
 }
-export function initOrizuWorkspace(options) {
-    const cwd = resolve(options?.cwd || process.cwd());
-    const root = getWorkspaceRoot(cwd);
-    const dryRun = Boolean(options?.dryRun);
-    const exists = workspaceExists(cwd);
-    const actions = [];
-    if (!exists) {
-        actions.push(`create ${WORKSPACE_DIR_NAME}/workspace.json, README.md, and generated/`);
+function gitignoreHasEntry(content, entry) {
+    return content
+        .split('\n')
+        .map(line => line.trim())
+        .some(line => line === entry || line === entry.replace(/\/$/, ''));
+}
+function missingGitignoreEntries(path, entries) {
+    if (!existsSync(path)) {
+        return entries;
+    }
+    const content = readFileSync(path, 'utf8');
+    return entries.filter(entry => !gitignoreHasEntry(content, entry));
+}
+function pushGitignore(operations, path, entries, reason) {
+    const missing = missingGitignoreEntries(path, entries);
+    if (missing.length > 0) {
+        operations.push(operation('append_gitignore', path, reason, { entries: missing }));
+    }
+}
+function existingTeamSlug(root) {
+    const manifest = readJsonManifest(join(root, 'orizu.team.json'));
+    return typeof manifest?.slug === 'string' ? manifest.slug : null;
+}
+function buildSetupPlan(options, includeFindings = true) {
+    const root = resolveWorkspaceRoot(options);
+    const currentTeamSlug = existingTeamSlug(root);
+    const requestedTeamSlug = options?.teamSlug ? normalizeSlug(options.teamSlug, 'local-team') : null;
+    const normalizedCurrentTeamSlug = currentTeamSlug ? normalizeSlug(currentTeamSlug, 'local-team') : null;
+    if (requestedTeamSlug && normalizedCurrentTeamSlug && requestedTeamSlug !== normalizedCurrentTeamSlug) {
+        throw new Error(`This directory is already an Orizu workspace for team '${normalizedCurrentTeamSlug}'. `
+            + `Run setup in another directory to set up team '${requestedTeamSlug}'.`);
+    }
+    const teamSlug = requestedTeamSlug || normalizedCurrentTeamSlug || 'local-team';
+    const existingProjectSlugs = projectDirectoryNames(join(root, 'projects'));
+    const projects = normalizeProjectSeeds({
+        ...options,
+        projects: options?.projects?.length
+            ? options.projects
+            : (!options?.projectSlug && existingProjectSlugs.length > 0
+                ? existingProjectSlugs.map(slug => ({ slug }))
+                : undefined),
+    });
+    const serviceOrigin = options?.serviceOrigin || options?.baseUrl || null;
+    const attachWorkspaceId = options?.attachWorkspaceId || null;
+    const operations = [];
+    pushCreateDir(operations, root, 'create workspace root');
+    for (const dir of WORKSPACE_ROOT_DIRS) {
+        pushCreateDir(operations, join(root, dir), `create root ${dir}/ directory`);
+    }
+    pushCreateDir(operations, join(root, WORKSPACE_DIR_NAME, 'generated'), 'create local generated cache directory');
+    pushCreateDir(operations, join(root, WORKSPACE_DIR_NAME, 'cache'), 'create local cache directory');
+    for (const project of projects) {
+        const projectRoot = join(root, 'projects', project.slug);
+        pushCreateDir(operations, projectRoot, `create ${project.slug} project directory`);
+        for (const dir of PROJECT_PRIMITIVE_DIRS) {
+            pushCreateDir(operations, join(projectRoot, dir), `create ${project.slug} ${dir}/ directory`);
+        }
+    }
+    pushCaseRename(operations, root, 'README.md', true);
+    pushCreateRootFile(operations, root, 'README.md', rootReadme(teamSlug), 'create team workbench README');
+    pushCreateFile(operations, join(root, 'orizu.team.json'), createTeamManifest({ teamSlug, teamId: options?.teamId || null, serviceOrigin, attachWorkspaceId, cliVersion: options?.cliVersion || null }), 'create team manifest');
+    pushCaseRename(operations, root, 'AGENTS.md', options?.fix);
+    pushCaseRename(operations, root, 'CLAUDE.md', options?.fix);
+    for (const variant of rootEntryCaseMatches(root, 'CLAUDE.md').nonCanonical) {
+        pushClaudeMigrationRepair(operations, root, variant, options);
+    }
+    pushExistingClaudeRepair(operations, root, options);
+    pushCreateRootFile(operations, root, 'AGENTS.md', AGENTS_MD, 'create canonical agent instructions');
+    pushCreateRootFile(operations, root, 'Memory.md', MEMORY_MD, 'create team memory file');
+    const claudePath = join(root, 'CLAUDE.md');
+    const claudeMatches = rootEntryCaseMatches(root, 'CLAUDE.md');
+    if (!claudeMatches.hasCanonical && claudeMatches.nonCanonical.length === 0) {
+        operations.push(options?.noSymlinks
+            ? operation('write_pointer_file', claudePath, 'create Claude pointer file', { content: CLAUDE_POINTER })
+            : operation('create_symlink', claudePath, 'link Claude instructions to AGENTS.md', { target: 'AGENTS.md' }));
+    }
+    pushGitignore(operations, join(root, '.gitignore'), ROOT_GITIGNORE_ENTRIES, 'seed root gitignore policy');
+    pushCreateFile(operations, join(root, WORKSPACE_DIR_NAME, 'README.md'), LOCAL_WORKSPACE_README, 'create local cache README');
+    for (const project of projects) {
+        const projectRoot = join(root, 'projects', project.slug);
+        pushCaseRename(operations, projectRoot, 'README.md', true);
+        pushCreateRootFile(operations, projectRoot, 'README.md', projectReadme(project.slug), 'create project README');
+        pushCreateFile(operations, join(projectRoot, 'memory.md'), PROJECT_MEMORY_MD, 'create project memory file');
+        pushCreateFile(operations, join(projectRoot, 'orizu.project.json'), createProjectManifest(teamSlug, project), 'create project manifest');
+        pushGitignore(operations, join(projectRoot, '.gitignore'), PROJECT_GITIGNORE_ENTRIES, 'seed project gitignore policy');
+    }
+    return {
+        root,
+        teamSlug,
+        projects,
+        operations,
+        findings: includeFindings ? validateWorkspaceContract({ ...options, workspaceRoot: root }) : [],
+        exists: workspaceExists(root),
+    };
+}
+export function planWorkspaceSetup(options) {
+    return buildSetupPlan(options);
+}
+function ensureParent(path) {
+    mkdirSync(dirname(path), { recursive: true });
+}
+function appendGitignore(path, entries) {
+    ensureParent(path);
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    const terminator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    const gap = existing.length > 0 ? '\n' : '';
+    const prefix = `${terminator}${gap}# Orizu workspace policy\n`;
+    writeFileSync(path, `${existing}${prefix}${entries.join('\n')}\n`, 'utf8');
+}
+function applyOperation(op) {
+    if (!op.safe) {
+        return false;
+    }
+    if (op.action === 'create_dir') {
+        mkdirSync(op.path, { recursive: true });
+        return true;
+    }
+    if (op.action === 'create_file' || op.action === 'write_pointer_file') {
+        if (pathExists(op.path)) {
+            return false;
+        }
+        ensureParent(op.path);
+        writeFileSync(op.path, op.content || '', 'utf8');
+        return true;
+    }
+    if (op.action === 'append_gitignore') {
+        appendGitignore(op.path, op.entries || []);
+        return true;
+    }
+    if (op.action === 'create_symlink') {
+        if (pathExists(op.path)) {
+            return false;
+        }
+        ensureParent(op.path);
+        try {
+            symlinkSync(op.target || 'AGENTS.md', op.path);
+        }
+        catch {
+            writeFileSync(op.path, CLAUDE_POINTER, 'utf8');
+        }
+        return true;
+    }
+    if (op.action === 'rename_file') {
+        if (!op.sourcePath || !pathExists(op.sourcePath)) {
+            return false;
+        }
+        ensureParent(op.path);
+        const sameCaseFoldedPath = op.sourcePath.toLowerCase() === op.path.toLowerCase();
+        if (sameCaseFoldedPath) {
+            const tempPath = `${op.path}.orizu-rename-${Date.now()}`;
+            renameSync(op.sourcePath, tempPath);
+            renameSync(tempPath, op.path);
+        }
+        else {
+            if (pathExists(op.path)) {
+                return false;
+            }
+            renameSync(op.sourcePath, op.path);
+        }
+        return true;
+    }
+    if (op.action === 'replace_file') {
+        ensureParent(op.path);
+        if (pathExists(op.path)) {
+            unlinkSync(op.path);
+        }
+        writeFileSync(op.path, op.content || '', 'utf8');
+        return true;
+    }
+    if (op.action === 'replace_symlink') {
+        ensureParent(op.path);
+        if (pathExists(op.path)) {
+            unlinkSync(op.path);
+        }
+        try {
+            symlinkSync(op.target || 'AGENTS.md', op.path);
+        }
+        catch {
+            writeFileSync(op.path, CLAUDE_POINTER, 'utf8');
+        }
+        return true;
+    }
+    return false;
+}
+function relativePath(root, path) {
+    const rel = relative(root, path);
+    return rel || '.';
+}
+function operationLabel(root, op) {
+    const path = relativePath(root, op.path);
+    if (op.action === 'create_dir')
+        return `create ${path}/`;
+    if (op.action === 'create_file')
+        return `create ${path}`;
+    if (op.action === 'append_gitignore')
+        return `append ${op.entries?.join(', ')} to ${path}`;
+    if (op.action === 'create_symlink')
+        return `link ${path} -> ${op.target}`;
+    if (op.action === 'write_pointer_file')
+        return `create ${path} pointer file`;
+    if (op.action === 'rename_file')
+        return `rename ${relativePath(root, op.sourcePath || '')} -> ${path}`;
+    if (op.action === 'replace_file')
+        return `repair ${path} pointer file`;
+    if (op.action === 'replace_symlink')
+        return `repair ${path} -> ${op.target}`;
+    return `repair ${path}`;
+}
+function finding(severity, code, message, path, fixable = false) {
+    return { severity, code, path, message, fixable };
+}
+function rootEntryNames(root) {
+    try {
+        return readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+}
+function checkCanonicalCase(root, canonical, findings) {
+    const matches = rootEntryNames(root).filter(name => name.toLowerCase() === canonical.toLowerCase());
+    const hasCanonical = matches.includes(canonical);
+    const nonCanonical = matches.filter(name => name !== canonical);
+    const canAutoRepair = !hasCanonical && nonCanonical.length <= 1;
+    if (!hasCanonical) {
+        findings.push(finding('error', 'missing_required_file', `Missing required root file ${canonical}.`, join(root, canonical), canAutoRepair));
+    }
+    for (const variant of nonCanonical) {
+        findings.push(finding('warning', 'non_canonical_case', `${variant} should be named ${canonical}.`, join(root, variant), canAutoRepair));
+    }
+    if (hasCanonical && nonCanonical.length > 0) {
+        findings.push(finding('error', 'case_conflict', `Both ${canonical} and non-canonical variants exist. Resolve manually.`, join(root, canonical), false));
+    }
+}
+function checkProjectFileCanonicalCase(projectRoot, projectName, canonical, findings, fixable) {
+    const matches = rootEntryNames(projectRoot).filter(name => name.toLowerCase() === canonical.toLowerCase());
+    const hasCanonical = matches.includes(canonical);
+    const nonCanonical = matches.filter(name => name !== canonical);
+    if (!hasCanonical) {
+        findings.push(finding('error', 'missing_project_file', `Missing project file projects/${projectName}/${canonical}.`, join(projectRoot, canonical), fixable));
+    }
+    for (const variant of nonCanonical) {
+        findings.push(finding('warning', 'non_canonical_case', `projects/${projectName}/${variant} should be named ${canonical}.`, join(projectRoot, variant), fixable));
     }
-    const gitignore = ensureGitignoreEntry(cwd, dryRun || exists);
-    if (!exists && gitignore.action) {
-        actions.push(gitignore.action);
+    if (hasCanonical && nonCanonical.length > 0) {
+        findings.push(finding('error', 'case_conflict', `Both projects/${projectName}/${canonical} and non-canonical variants exist. Resolve manually.`, join(projectRoot, canonical), false));
+    }
+}
+export function readJsonManifest(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function validateManifest(path, findings) {
+    const parsed = readJsonManifest(path);
+    if (!parsed) {
+        findings.push(finding('error', 'invalid_manifest_json', 'Manifest must be valid JSON with an object root.', path, false));
+        return;
+    }
+    if (parsed.schemaVersion !== WORKSPACE_SCHEMA_VERSION) {
+        findings.push(finding('error', 'invalid_schema_version', `Manifest schemaVersion must be ${WORKSPACE_SCHEMA_VERSION}.`, path, false));
+    }
+    if (typeof parsed.kind !== 'string' || parsed.kind.length === 0) {
+        findings.push(finding('error', 'missing_manifest_kind', 'Manifest must include kind.', path, false));
+    }
+    if (typeof parsed.slug !== 'string' && typeof parsed.runId !== 'string' && typeof parsed.sessionId !== 'string') {
+        findings.push(finding('error', 'missing_manifest_identity', 'Manifest must include slug, runId, or sessionId.', path, false));
+    }
+    const canonical = parsed.canonical;
+    if (!canonical || typeof canonical !== 'object' || Array.isArray(canonical)) {
+        findings.push(finding('error', 'missing_canonical', 'Manifest must include canonical owner and repoState.', path, false));
+        return;
+    }
+    const canonicalRecord = canonical;
+    if (!hasAllowedValue(CANONICAL_OWNERS, canonicalRecord.owner)) {
+        findings.push(finding('error', 'invalid_canonical_owner', `canonical.owner must be one of ${CANONICAL_OWNERS.join(', ')}.`, path, false));
+    }
+    if (!hasAllowedValue(REPO_STATES, canonicalRecord.repoState)) {
+        findings.push(finding('error', 'invalid_repo_state', `canonical.repoState must be one of ${REPO_STATES.join(', ')}.`, path, false));
+    }
+    if (parsed.kind === 'team') {
+        const setup = parsed.setup;
+        if (!setup || typeof setup !== 'object' || Array.isArray(setup)) {
+            findings.push(finding('warning', 'missing_setup_metadata', 'Team manifest should include setup metadata.', path, false));
+        }
+    }
+}
+function collectManagedWorkspaceManifestPaths(root) {
+    const paths = [];
+    const ignored = new Set(['.git', 'node_modules', '.next', 'dist', 'build', WORKSPACE_DIR_NAME]);
+    const rootManifest = join(root, 'orizu.team.json');
+    if (existsSync(rootManifest)) {
+        paths.push(rootManifest);
+    }
+    function walk(dir, depth) {
+        if (depth > 8 || !existsSync(dir)) {
+            return;
+        }
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (ignored.has(entry.name)) {
+                continue;
+            }
+            const path = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(path, depth + 1);
+            }
+            else if (/^orizu\..+\.json$/.test(entry.name)) {
+                paths.push(path);
+            }
+        }
+    }
+    const projectsRoot = join(root, 'projects');
+    for (const projectName of projectDirectoryNames(projectsRoot)) {
+        const projectRoot = join(projectsRoot, projectName);
+        const projectManifest = join(projectRoot, 'orizu.project.json');
+        if (existsSync(projectManifest)) {
+            paths.push(projectManifest);
+        }
+        for (const primitiveDir of PROJECT_PRIMITIVE_DIRS) {
+            walk(join(projectRoot, primitiveDir), 0);
+        }
     }
+    return paths;
+}
+function collectNamedPaths(root, name) {
+    const paths = [];
+    const ignored = new Set(['.git', 'node_modules', '.next', 'dist', 'build', WORKSPACE_DIR_NAME]);
+    function walk(dir, depth) {
+        if (depth > 8 || !existsSync(dir)) {
+            return;
+        }
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (ignored.has(entry.name)) {
+                continue;
+            }
+            const path = join(dir, entry.name);
+            if (entry.name === name) {
+                paths.push(path);
+            }
+            if (entry.isDirectory()) {
+                walk(path, depth + 1);
+            }
+        }
+    }
+    walk(root, 0);
+    return paths;
+}
+function validateClaudeFile(root, noSymlinks, findings) {
+    const path = join(root, 'CLAUDE.md');
+    const stat = lstatIfExists(path);
+    if (!stat) {
+        return;
+    }
+    if (stat.isSymbolicLink()) {
+        const target = readlinkSync(path);
+        if (target !== 'AGENTS.md') {
+            findings.push(finding('error', 'invalid_claude_symlink', 'CLAUDE.md must symlink to AGENTS.md.', path, true));
+        }
+        if (noSymlinks) {
+            findings.push(finding('warning', 'unexpected_claude_symlink', 'CLAUDE.md is a symlink but --no-symlinks expects a pointer file.', path, true));
+        }
+        return;
+    }
+    const content = readFileSync(path, 'utf8');
+    if (!content.includes('AGENTS.md')) {
+        findings.push(finding('error', 'invalid_claude_pointer', 'CLAUDE.md must point readers to AGENTS.md when it is not a symlink.', path, false));
+    }
+}
+function validateAgentsFile(root, findings) {
+    const path = join(root, 'AGENTS.md');
+    if (!existsSync(path)) {
+        return;
+    }
+    const content = readFileSync(path, 'utf8');
+    const hasSkillBlock = content.includes(ORIZU_CLI_AGENTS_START_MARKER) &&
+        content.includes(ORIZU_CLI_AGENTS_END_MARKER);
+    if (hasSkillBlock) {
+        findings.push(finding('error', 'embedded_skill_block', 'AGENTS.md contains the full Orizu CLI skill block. Keep root AGENTS.md concise and move detailed CLI guidance to installed skills or `orizu --help`.', path, false));
+    }
+}
+function projectDirectoryNames(projectsRoot) {
+    try {
+        return readdirSync(projectsRoot, { withFileTypes: true })
+            .filter(entry => entry.isDirectory())
+            .map(entry => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function validateProjectContract(root, options, findings) {
+    const projectsRoot = join(root, 'projects');
+    if (!existsSync(projectsRoot)) {
+        return;
+    }
+    const expectedProjects = options?.projects?.length
+        ? options.projects.map(project => normalizeSlug(project.slug, 'local-project'))
+        : (options?.projectSlug ? [normalizeSlug(options.projectSlug, 'local-project')] : null);
+    const projectNames = expectedProjects || projectDirectoryNames(projectsRoot);
+    const canRepairProject = Boolean(expectedProjects?.length);
+    if (projectNames.length === 0) {
+        findings.push(finding('error', 'missing_project_directory', 'Workspace must include at least one project directory under projects/.', projectsRoot, canRepairProject));
+        return;
+    }
+    for (const name of projectNames) {
+        const projectRoot = join(projectsRoot, name);
+        if (!existsSync(projectRoot)) {
+            findings.push(finding('error', 'missing_project_directory', `Missing project directory projects/${name}/.`, projectRoot, canRepairProject));
+            continue;
+        }
+        for (const file of PROJECT_ROOT_FILES) {
+            if (/^[A-Z]/.test(file)) {
+                checkProjectFileCanonicalCase(projectRoot, name, file, findings, canRepairProject);
+            }
+            else {
+                const path = join(projectRoot, file);
+                if (!existsSync(path)) {
+                    findings.push(finding('error', 'missing_project_file', `Missing project file projects/${name}/${file}.`, path, canRepairProject));
+                }
+            }
+        }
+        for (const dir of PROJECT_PRIMITIVE_DIRS) {
+            const path = join(projectRoot, dir);
+            if (!existsSync(path)) {
+                findings.push(finding('error', 'missing_project_dir', `Missing project directory projects/${name}/${dir}/.`, path, canRepairProject));
+            }
+        }
+        const projectGitignore = join(projectRoot, '.gitignore');
+        if (existsSync(projectGitignore) && missingGitignoreEntries(projectGitignore, [`${WORKSPACE_DIR_NAME}/`]).length > 0) {
+            findings.push(finding('error', 'missing_project_orizu_gitignore', `.orizu/ must be ignored by default in projects/${name}/.`, projectGitignore, canRepairProject));
+        }
+    }
+}
+export function validateWorkspaceContract(options) {
+    const root = resolveWorkspaceRoot(options);
+    const findings = [];
+    if (!existsSync(root)) {
+        findings.push(finding('error', 'missing_workspace_root', 'Workspace root does not exist.', root, true));
+        return findings;
+    }
+    for (const file of WORKSPACE_ROOT_FILES) {
+        if (/^[A-Z]/.test(file)) {
+            checkCanonicalCase(root, file, findings);
+        }
+        else {
+            const path = join(root, file);
+            if (!existsSync(path)) {
+                findings.push(finding('error', 'missing_required_file', `Missing required root file ${file}.`, path, true));
+            }
+        }
+    }
+    for (const dir of WORKSPACE_ROOT_DIRS) {
+        const path = join(root, dir);
+        if (!existsSync(path)) {
+            findings.push(finding('error', 'missing_required_dir', `Missing required root directory ${dir}/.`, path, true));
+        }
+    }
+    const rootGitignore = join(root, '.gitignore');
+    if (existsSync(rootGitignore) && missingGitignoreEntries(rootGitignore, [`${WORKSPACE_DIR_NAME}/`]).length > 0) {
+        findings.push(finding('error', 'missing_orizu_gitignore', '.orizu/ must be ignored by default.', rootGitignore, true));
+    }
+    validateClaudeFile(root, Boolean(options?.noSymlinks), findings);
+    validateAgentsFile(root, findings);
+    validateProjectContract(root, options, findings);
+    for (const path of collectManagedWorkspaceManifestPaths(root)) {
+        validateManifest(path, findings);
+    }
+    for (const path of collectNamedPaths(root, '.gitadd')) {
+        findings.push(finding('error', 'gitadd_not_supported', '.gitadd is not part of the Orizu workspace contract.', path, false));
+    }
+    return findings;
+}
+export function initOrizuWorkspace(options) {
+    const dryRun = Boolean(options?.dryRun);
+    const validateOnly = Boolean(options?.validateOnly);
+    const plan = buildSetupPlan(options, dryRun || validateOnly);
+    const beforeExists = plan.exists;
     if (dryRun) {
         return {
-            root,
-            state: exists ? 'exists' : 'would-create',
+            root: plan.root,
+            state: beforeExists ? 'exists' : 'would-create',
+            gitignoreUpdated: false,
+            actions: plan.operations.map(op => operationLabel(plan.root, op)),
+            operations: plan.operations,
+            findings: plan.findings,
+        };
+    }
+    if (validateOnly) {
+        const hasErrors = plan.findings.some(item => item.severity === 'error');
+        return {
+            root: plan.root,
+            state: hasErrors ? 'invalid' : 'validated',
             gitignoreUpdated: false,
-            actions,
+            actions: [],
+            operations: [],
+            findings: plan.findings,
         };
     }
-    if (exists) {
-        return { root, state: 'exists', gitignoreUpdated: false, actions: [] };
-    }
-    mkdirSync(join(root, 'generated'), { recursive: true });
-    writeFileSync(join(root, 'README.md'), WORKSPACE_README, 'utf8');
-    writeFileSync(join(root, 'workspace.json'), `${JSON.stringify({
-        version: 1,
-        server: options?.baseUrl || null,
-        createdByCliVersion: options?.cliVersion || null,
-    }, null, 2)}\n`, 'utf8');
-    return { root, state: 'created', gitignoreUpdated: gitignore.updated, actions };
+    let applied = 0;
+    let gitignoreUpdated = false;
+    for (const op of plan.operations) {
+        const didApply = applyOperation(op);
+        if (didApply) {
+            applied += 1;
+            if (op.action === 'append_gitignore') {
+                gitignoreUpdated = true;
+            }
+        }
+    }
+    const findings = validateWorkspaceContract({ ...options, workspaceRoot: plan.root });
+    return {
+        root: plan.root,
+        state: beforeExists ? (applied > 0 ? 'repaired' : 'exists') : 'created',
+        gitignoreUpdated,
+        actions: plan.operations.map(op => operationLabel(plan.root, op)),
+        operations: plan.operations,
+        findings,
+    };
 }