@open-agent-toolkit/cli 0.1.5 → 0.1.6

package/dist/projects/split/validation.js

@@ -0,0 +1,104 @@
+function findDependencyCycle(plan) {
+    const childSlugs = new Set(plan.children.map((child) => child.slug));
+    const graph = new Map(plan.children.map((child) => [
+        child.slug,
+        child.knownDependencies.filter((dependency) => childSlugs.has(dependency)),
+    ]));
+    const visiting = new Set();
+    const visited = new Set();
+    const stack = [];
+    function visit(slug) {
+        if (visiting.has(slug)) {
+            return [...stack.slice(stack.indexOf(slug)), slug];
+        }
+        if (visited.has(slug)) {
+            return null;
+        }
+        visiting.add(slug);
+        stack.push(slug);
+        for (const dependency of graph.get(slug) ?? []) {
+            const cycle = visit(dependency);
+            if (cycle) {
+                return cycle;
+            }
+        }
+        stack.pop();
+        visiting.delete(slug);
+        visited.add(slug);
+        return null;
+    }
+    for (const child of plan.children) {
+        const cycle = visit(child.slug);
+        if (cycle) {
+            return cycle;
+        }
+    }
+    return null;
+}
+export function validateChildPlan(plan, existingSlugs) {
+    const errors = [];
+    const seenChildSlugs = new Set();
+    const childSlugs = new Set(plan.children.map((child) => child.slug));
+    if (existingSlugs.has(plan.parentSlug)) {
+        errors.push({
+            code: 'slug-collision-existing',
+            message: `Parent slug already exists: ${plan.parentSlug}`,
+            slug: plan.parentSlug,
+        });
+    }
+    for (const child of plan.children) {
+        if (existingSlugs.has(child.slug)) {
+            errors.push({
+                code: 'slug-collision-existing',
+                message: `Child slug already exists: ${child.slug}`,
+                slug: child.slug,
+            });
+        }
+        if (seenChildSlugs.has(child.slug)) {
+            errors.push({
+                code: 'duplicate-child-slug',
+                message: `Duplicate child slug: ${child.slug}`,
+                slug: child.slug,
+            });
+        }
+        seenChildSlugs.add(child.slug);
+        if (child.slug === plan.parentSlug) {
+            errors.push({
+                code: 'parent-child-slug-collision',
+                message: `Parent slug collides with child slug: ${child.slug}`,
+                slug: child.slug,
+            });
+        }
+        for (const dependency of child.knownDependencies) {
+            if (dependency === child.slug || !childSlugs.has(dependency)) {
+                errors.push({
+                    code: 'unknown-dependency',
+                    message: `Dependency ${dependency} is not a sibling of ${child.slug}`,
+                    slug: child.slug,
+                });
+            }
+        }
+    }
+    if (plan.foundationChild && !childSlugs.has(plan.foundationChild)) {
+        errors.push({
+            code: 'unknown-foundation-child',
+            message: `foundationChild is not in children: ${plan.foundationChild}`,
+            slug: plan.foundationChild,
+        });
+    }
+    if (!childSlugs.has(plan.initialActiveChild)) {
+        errors.push({
+            code: 'unknown-initial-active-child',
+            message: `initialActiveChild is not in children: ${plan.initialActiveChild}`,
+            slug: plan.initialActiveChild,
+        });
+    }
+    const cycle = findDependencyCycle(plan);
+    if (cycle) {
+        errors.push({
+            code: 'dependency-cycle',
+            message: `Child dependencies contain a cycle: ${cycle.join(' -> ')}`,
+        });
+    }
+    return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}

package/dist/projects/split/write-parent.d.ts

@@ -0,0 +1,16 @@
+import { scaffoldProject as defaultScaffoldProject, type ScaffoldProjectResult } from '../../commands/project/new/scaffold.js';
+import type { SplitPlanDocument } from './child-plan.js';
+export interface SplitProjectContext {
+    repoRoot: string;
+    projectsRoot?: string;
+    today?: string;
+    nowUtc?: string;
+    env?: NodeJS.ProcessEnv;
+    scaffoldProject?: typeof defaultScaffoldProject;
+}
+export interface WriteCoordinationParentResult {
+    parentProjectPath: string;
+    scaffold: ScaffoldProjectResult;
+}
+export declare function writeCoordinationParent(document: SplitPlanDocument, context: SplitProjectContext): Promise<WriteCoordinationParentResult>;
+//# sourceMappingURL=write-parent.d.ts.map

package/dist/projects/split/write-parent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-parent.d.ts","sourceRoot":"","sources":["../../../src/projects/split/write-parent.ts"],"names":[],"mappings":"AAGA,OAAO,EACL,eAAe,IAAI,sBAAsB,EACzC,KAAK,qBAAqB,EAC3B,MAAM,gCAAgC,CAAC;AAMxC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,sBAAsB,CAAC;CACjD;AA6JD,MAAM,WAAW,6BAA6B;IAC5C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,qBAAqB,CAAC;CACjC;AAED,wBAAsB,uBAAuB,CAC3C,QAAQ,EAAE,iBAAiB,EAC3B,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,6BAA6B,CAAC,CA4DxC"}

package/dist/projects/split/write-parent.js

@@ -0,0 +1,176 @@
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { scaffoldProject as defaultScaffoldProject, } from '../../commands/project/new/scaffold.js';
+import { getFrontmatterBlock } from '../../commands/shared/frontmatter.js';
+import { replaceFrontmatter } from '../../commands/shared/frontmatter-write.js';
+import { assertValidProjectStateFilesystemContent } from '../../validation/project-state.js';
+import YAML from 'yaml';
+function readObjectFrontmatter(content, filePath) {
+    const block = getFrontmatterBlock(content);
+    if (!block) {
+        throw new Error(`${filePath} is missing frontmatter`);
+    }
+    const parsed = YAML.parse(block);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${filePath} frontmatter must be an object`);
+    }
+    return parsed;
+}
+async function writeObjectFrontmatter(filePath, updates) {
+    const content = await readFile(filePath, 'utf8');
+    const frontmatter = readObjectFrontmatter(content, filePath);
+    updates(frontmatter);
+    await writeFile(filePath, replaceFrontmatter(content, YAML.stringify(frontmatter).trimEnd()), 'utf8');
+}
+function projectPathFor(projectsRoot, slug) {
+    return join(projectsRoot, slug).split('\\').join('/');
+}
+function renderParentDiscovery(document) {
+    const { plan } = document;
+    const orderedChildren = plan.children
+        .slice()
+        .sort((left, right) => left.order - right.order);
+    const childSlugs = orderedChildren.map((child) => child.slug);
+    const childSummary = orderedChildren
+        .map((child) => {
+        const siblings = childSlugs.filter((slug) => slug !== child.slug);
+        return [
+            `${child.order}. ${child.slug}: ${child.description ?? 'No description provided.'}`,
+            `   - Dependencies: ${child.knownDependencies.length > 0 ? child.knownDependencies.join(', ') : 'None'}`,
+            `   - Siblings: ${siblings.length > 0 ? siblings.join(', ') : 'None'}`,
+            `   - Inherited context: ${child.inheritedContext || 'None provided.'}`,
+        ].join('\n');
+    })
+        .join('\n');
+    const inheritedContext = orderedChildren
+        .map((child) => `- ${child.slug}: ${child.inheritedContext || 'None provided.'}`)
+        .join('\n');
+    const sharedConstraints = [
+        plan.foundationChild ? `- Foundation child: ${plan.foundationChild}` : null,
+        `- Initial active child: ${plan.initialActiveChild}`,
+    ]
+        .filter((line) => Boolean(line))
+        .join('\n');
+    return [
+        '---',
+        'oat_status: complete',
+        'oat_ready_for: null',
+        'oat_blockers: []',
+        'oat_generated: false',
+        '---',
+        '',
+        `# Discovery: ${plan.parentSlug}`,
+        '',
+        '## Split Rationale',
+        '',
+        `Origin: ${document.origin}`,
+        `Interactive: ${document.interactive ? 'true' : 'false'}`,
+        `Why: ${plan.integrationSketch ?? 'Split child scopes were captured in a coordination parent for tracked sequencing and integration.'}`,
+        '',
+        '## Ordered Children',
+        '',
+        childSummary,
+        '',
+        '## Inherited Broad Context',
+        '',
+        inheritedContext || 'No inherited broad context provided.',
+        '',
+        '## Shared Constraints',
+        '',
+        sharedConstraints || 'No shared constraints provided.',
+        '',
+        '## Integration Sketch',
+        '',
+        plan.integrationSketch ?? 'No integration sketch provided.',
+        '',
+    ].join('\n');
+}
+function renderParentStateBody(document) {
+    const childList = document.plan.children
+        .slice()
+        .sort((left, right) => left.order - right.order)
+        .map((child) => `- ${child.slug}`)
+        .join('\n');
+    return [
+        `# Project State: ${document.plan.parentSlug}`,
+        '',
+        '**Status:** Coordination',
+        '',
+        '## Current Phase',
+        '',
+        'Decomposition coordination - split children are tracked as implementation projects.',
+        '',
+        '## Artifacts',
+        '',
+        '- **Discovery:** `discovery.md` (coordination summary)',
+        '- **Split Plan:** `references/split-plan.json` (persisted resume source)',
+        '- **Spec:** N/A (coordination parent)',
+        '- **Design:** N/A (coordination parent)',
+        '- **Plan:** N/A (coordination parent)',
+        '- **Implementation:** N/A (coordination parent)',
+        '',
+        '## Children',
+        '',
+        childList || '- None.',
+        '',
+        '## Progress',
+        '',
+        '- Split plan persisted',
+        '- Child projects selected for implementation tracking',
+        '',
+        '## Blockers',
+        '',
+        'None',
+        '',
+        '## Next Milestone',
+        '',
+        `Continue through active child \`${document.plan.initialActiveChild}\`.`,
+        '',
+    ].join('\n');
+}
+async function replaceMarkdownBody(filePath, body) {
+    const content = await readFile(filePath, 'utf8');
+    const frontmatter = getFrontmatterBlock(content);
+    if (!frontmatter) {
+        throw new Error(`${filePath} is missing frontmatter`);
+    }
+    await writeFile(filePath, `---\n${frontmatter}\n---\n\n${body}`, 'utf8');
+}
+export async function writeCoordinationParent(document, context) {
+    const scaffoldProject = context.scaffoldProject ?? defaultScaffoldProject;
+    const scaffold = await scaffoldProject({
+        repoRoot: context.repoRoot,
+        projectName: document.plan.parentSlug,
+        mode: 'quick',
+        setActive: false,
+        refreshDashboard: false,
+        env: context.env,
+        today: context.today,
+        nowUtc: context.nowUtc,
+    });
+    const parentProjectPath = scaffold.projectPath;
+    const parentRoot = join(context.repoRoot, parentProjectPath);
+    const statePath = join(parentRoot, 'state.md');
+    await writeObjectFrontmatter(statePath, (frontmatter) => {
+        frontmatter['oat_kind'] = 'coordination';
+        frontmatter['oat_workflow_mode'] = 'quick';
+        frontmatter['oat_hill_checkpoints'] = [];
+        frontmatter['oat_children'] = document.plan.children
+            .slice()
+            .sort((left, right) => left.order - right.order)
+            .map((child) => child.slug);
+    });
+    await replaceMarkdownBody(statePath, renderParentStateBody(document));
+    await mkdir(join(parentRoot, 'references'), { recursive: true });
+    await writeFile(join(parentRoot, 'references', 'split-plan.json'), `${JSON.stringify(document, null, 2)}\n`, 'utf8');
+    await writeFile(join(parentRoot, 'discovery.md'), renderParentDiscovery(document), 'utf8');
+    await Promise.all(['spec.md', 'design.md', 'plan.md', 'implementation.md'].map((file) => rm(join(parentRoot, file), { force: true })));
+    await assertValidProjectStateFilesystemContent(await readFile(statePath, 'utf8'), {
+        filePath: statePath,
+        projectPath: parentRoot,
+    });
+    return {
+        parentProjectPath: projectPathFor(context.projectsRoot ?? scaffold.projectsRoot, document.plan.parentSlug),
+        scaffold,
+    };
+}

package/dist/validation/project-state.d.ts

@@ -0,0 +1,50 @@
+import { readdir as defaultReaddir, readFile as defaultReadFile } from 'node:fs/promises';
+import { type ProjectStateKind, type ProjectStatePhase } from '../commands/shared/frontmatter.js';
+export interface NormalizedProjectState {
+    oat_kind: ProjectStateKind;
+    oat_phase?: ProjectStatePhase;
+    oat_phase_status?: string;
+    oat_parent?: string;
+    oat_siblings: string[];
+    oat_depends_on: string[];
+    oat_children: string[];
+}
+export interface ProjectStateValidationError {
+    code: string;
+    message: string;
+}
+export interface ProjectStateValidationInput {
+    slug?: string;
+    frontmatter: Record<string, unknown>;
+    relatedProjects?: ProjectStateSnapshot[];
+}
+export interface ProjectStateSnapshot {
+    slug: string;
+    frontmatter: Record<string, unknown>;
+}
+export interface ProjectStateValidationResult {
+    ok: boolean;
+    state: NormalizedProjectState;
+    errors: ProjectStateValidationError[];
+}
+export interface AssertProjectStateContentOptions {
+    filePath?: string;
+    slug?: string;
+    relatedProjects?: ProjectStateSnapshot[];
+}
+export interface AssertProjectStateFilesystemContentOptions extends Omit<AssertProjectStateContentOptions, 'relatedProjects'> {
+    projectPath: string;
+    projectsRoot?: string;
+    readdir?: typeof defaultReaddir;
+    readFile?: typeof defaultReadFile;
+}
+export declare function validateProjectState(input: ProjectStateValidationInput): ProjectStateValidationResult;
+export declare function assertValidProjectStateContent(content: string, options?: AssertProjectStateContentOptions): void;
+export declare function readRelatedProjectStateSnapshots(options: {
+    projectsRoot: string;
+    currentProjectSlug: string;
+    readdir?: typeof defaultReaddir;
+    readFile?: typeof defaultReadFile;
+}): Promise<ProjectStateSnapshot[]>;
+export declare function assertValidProjectStateFilesystemContent(content: string, options: AssertProjectStateFilesystemContentOptions): Promise<void>;
+//# sourceMappingURL=project-state.d.ts.map

package/dist/validation/project-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-state.d.ts","sourceRoot":"","sources":["../../src/validation/project-state.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,IAAI,cAAc,EACzB,QAAQ,IAAI,eAAe,EAC5B,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EAIL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,8BAA8B,CAAC;AAGtC,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,eAAe,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,sBAAsB,CAAC;IAC9B,MAAM,EAAE,2BAA2B,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,oBAAoB,EAAE,CAAC;CAC1C;AAED,MAAM,WAAW,0CAA2C,SAAQ,IAAI,CACtE,gCAAgC,EAChC,iBAAiB,CAClB;IACC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,cAAc,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,eAAe,CAAC;CACnC;AAmND,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,2BAA2B,GACjC,4BAA4B,CAqE9B;AAED,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,gCAAqC,GAC7C,IAAI,CAYN;AAED,wBAAsB,gCAAgC,CAAC,OAAO,EAAE;IAC9D,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,cAAc,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,eAAe,CAAC;CACnC,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAwBlC;AAED,wBAAsB,wCAAwC,CAC5D,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,0CAA0C,GAClD,OAAO,CAAC,IAAI,CAAC,CAkDf"}

package/dist/validation/project-state.js

@@ -0,0 +1,279 @@
+import { readdir as defaultReaddir, readFile as defaultReadFile, } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { getFrontmatterBlock, isProjectStateKind, isProjectStatePhase, } from '../commands/shared/frontmatter.js';
+import YAML from 'yaml';
+function readStringField(frontmatter, key) {
+    const value = frontmatter[key];
+    return typeof value === 'string' ? value : undefined;
+}
+function readStringArrayField(frontmatter, key, errors) {
+    const value = frontmatter[key];
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (Array.isArray(value) && value.every((item) => typeof item === 'string')) {
+        return [...value];
+    }
+    errors.push({
+        code: 'invalid-string-array',
+        message: `${key} must be an array of strings`,
+    });
+    return [];
+}
+function readKind(frontmatter) {
+    const rawKind = readStringField(frontmatter, 'oat_kind');
+    return rawKind && isProjectStateKind(rawKind) ? rawKind : 'implementation';
+}
+function sameStringSet(left, right) {
+    if (left.length !== right.length) {
+        return false;
+    }
+    const sortedLeft = [...left].sort();
+    const sortedRight = [...right].sort();
+    return sortedLeft.every((value, index) => value === sortedRight[index]);
+}
+function graphHasCycle(graph) {
+    const visiting = new Set();
+    const visited = new Set();
+    function visit(slug) {
+        if (visiting.has(slug)) {
+            return true;
+        }
+        if (visited.has(slug)) {
+            return false;
+        }
+        visiting.add(slug);
+        for (const dependency of graph.get(slug) ?? []) {
+            if (graph.has(dependency) && visit(dependency)) {
+                return true;
+            }
+        }
+        visiting.delete(slug);
+        visited.add(slug);
+        return false;
+    }
+    return [...graph.keys()].some((slug) => visit(slug));
+}
+function validateChildLinkage(input, state, errors) {
+    if (!state.oat_parent) {
+        return;
+    }
+    const relatedProjects = input.relatedProjects ?? [];
+    const parent = relatedProjects.find((project) => project.slug === state.oat_parent);
+    if (!parent && input.relatedProjects !== undefined) {
+        errors.push({
+            code: 'parent-missing',
+            message: `oat_parent ${state.oat_parent} must reference an existing project`,
+        });
+    }
+    if (parent && readKind(parent.frontmatter) !== 'coordination') {
+        errors.push({
+            code: 'parent-not-coordination',
+            message: `oat_parent ${state.oat_parent} must reference a coordination project`,
+        });
+    }
+    for (const dependency of state.oat_depends_on) {
+        if (!state.oat_siblings.includes(dependency)) {
+            errors.push({
+                code: 'depends-on-non-sibling',
+                message: `oat_depends_on entry ${dependency} must be listed in oat_siblings`,
+            });
+        }
+    }
+    if (input.slug && parent) {
+        const parentChildren = readStringArrayField(parent.frontmatter, 'oat_children', errors);
+        if (parentChildren.length > 0) {
+            const expectedSiblings = parentChildren.filter((childSlug) => childSlug !== input.slug);
+            if (!sameStringSet(state.oat_siblings, expectedSiblings)) {
+                errors.push({
+                    code: 'siblings-must-match-parent-children',
+                    message: 'oat_siblings must equal parent oat_children minus the current child',
+                });
+            }
+        }
+    }
+    const graph = new Map();
+    if (input.slug) {
+        graph.set(input.slug, state.oat_depends_on);
+    }
+    for (const project of relatedProjects) {
+        if (project.slug === input.slug || project.slug === state.oat_parent) {
+            continue;
+        }
+        if (readStringField(project.frontmatter, 'oat_parent') !== state.oat_parent) {
+            continue;
+        }
+        graph.set(project.slug, readStringArrayField(project.frontmatter, 'oat_depends_on', errors));
+    }
+    if (graphHasCycle(graph)) {
+        errors.push({
+            code: 'sibling-dependency-cycle',
+            message: 'oat_depends_on across sibling projects must be acyclic',
+        });
+    }
+}
+function validateInheritedContextGate(frontmatter, state, errors) {
+    if (!state.oat_parent) {
+        return;
+    }
+    if (readStringField(frontmatter, 'oat_status') === 'complete' &&
+        frontmatter['oat_inherited_context_revalidated'] === false) {
+        errors.push({
+            code: 'inherited-context-revalidation-required',
+            message: 'child discovery cannot complete until oat_inherited_context_revalidated is true',
+        });
+    }
+}
+function validateCoordinationParent(state, errors) {
+    if (state.oat_phase !== 'decomposition') {
+        return;
+    }
+    if (state.oat_children.length === 0) {
+        errors.push({
+            code: 'decomposition-requires-children',
+            message: 'oat_phase: decomposition requires non-empty oat_children',
+        });
+    }
+}
+function parseFrontmatterObject(content, filePath) {
+    const frontmatter = getFrontmatterBlock(content);
+    if (!frontmatter) {
+        throw new Error(`${filePath} is missing frontmatter`);
+    }
+    const parsed = YAML.parse(frontmatter);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${filePath} frontmatter must be a YAML object`);
+    }
+    return parsed;
+}
+export function validateProjectState(input) {
+    const errors = [];
+    const rawKind = readStringField(input.frontmatter, 'oat_kind');
+    const rawPhase = readStringField(input.frontmatter, 'oat_phase');
+    const rawPhaseStatus = readStringField(input.frontmatter, 'oat_phase_status');
+    const rawParent = readStringField(input.frontmatter, 'oat_parent');
+    let kind = 'implementation';
+    if (rawKind) {
+        if (isProjectStateKind(rawKind)) {
+            kind = rawKind;
+        }
+        else {
+            errors.push({
+                code: 'invalid-oat-kind',
+                message: `Invalid oat_kind: ${rawKind}`,
+            });
+        }
+    }
+    let phase;
+    if (rawPhase) {
+        if (isProjectStatePhase(rawPhase)) {
+            phase = rawPhase;
+        }
+        else {
+            errors.push({
+                code: 'invalid-oat-phase',
+                message: `Invalid oat_phase: ${rawPhase}`,
+            });
+        }
+    }
+    if (phase === 'decomposition' && kind !== 'coordination') {
+        errors.push({
+            code: 'decomposition-requires-coordination',
+            message: 'oat_phase: decomposition requires oat_kind: coordination',
+        });
+    }
+    const state = {
+        oat_kind: kind,
+        oat_phase: phase,
+        oat_phase_status: rawPhaseStatus,
+        oat_parent: rawParent,
+        oat_siblings: readStringArrayField(input.frontmatter, 'oat_siblings', errors),
+        oat_depends_on: readStringArrayField(input.frontmatter, 'oat_depends_on', errors),
+        oat_children: readStringArrayField(input.frontmatter, 'oat_children', errors),
+    };
+    validateChildLinkage(input, state, errors);
+    validateInheritedContextGate(input.frontmatter, state, errors);
+    validateCoordinationParent(state, errors);
+    return {
+        ok: errors.length === 0,
+        state,
+        errors,
+    };
+}
+export function assertValidProjectStateContent(content, options = {}) {
+    const filePath = options.filePath ?? 'state.md';
+    const frontmatter = parseFrontmatterObject(content, filePath);
+    const result = validateProjectState({
+        frontmatter,
+        slug: options.slug,
+        relatedProjects: options.relatedProjects,
+    });
+    if (!result.ok) {
+        throw new Error(result.errors.map((error) => error.message).join('; '));
+    }
+}
+export async function readRelatedProjectStateSnapshots(options) {
+    const readdir = options.readdir ?? defaultReaddir;
+    const readFile = options.readFile ?? defaultReadFile;
+    const snapshots = [];
+    const entries = await readdir(options.projectsRoot, { withFileTypes: true });
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === options.currentProjectSlug) {
+            continue;
+        }
+        const statePath = join(options.projectsRoot, entry.name, 'state.md');
+        try {
+            const content = await readFile(statePath, 'utf8');
+            snapshots.push({
+                slug: entry.name,
+                frontmatter: parseFrontmatterObject(content, statePath),
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return snapshots;
+}
+export async function assertValidProjectStateFilesystemContent(content, options) {
+    const slug = options.slug ?? basename(options.projectPath);
+    const relatedProjects = await readRelatedProjectStateSnapshots({
+        projectsRoot: options.projectsRoot ?? join(options.projectPath, '..'),
+        currentProjectSlug: slug,
+        readdir: options.readdir,
+        readFile: options.readFile,
+    });
+    const frontmatter = parseFrontmatterObject(content, options.filePath ?? 'state.md');
+    const result = validateProjectState({
+        frontmatter,
+        slug,
+        relatedProjects,
+    });
+    const errors = [...result.errors];
+    if (result.state.oat_kind === 'coordination' ||
+        result.state.oat_phase === 'decomposition') {
+        const readdir = options.readdir ?? defaultReaddir;
+        const entries = await readdir(options.projectPath, {
+            withFileTypes: true,
+        });
+        const executableArtifacts = new Set([
+            'spec.md',
+            'design.md',
+            'plan.md',
+            'implementation.md',
+        ]);
+        const presentExecutableArtifacts = entries
+            .filter((entry) => entry.isFile() && executableArtifacts.has(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+        if (presentExecutableArtifacts.length > 0) {
+            errors.push({
+                code: 'coordination-parent-no-executable-artifacts',
+                message: `coordination projects must not contain executable phase artifacts: ${presentExecutableArtifacts.join(', ')}`,
+            });
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(errors.map((error) => error.message).join('; '));
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -33,7 +33,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.5"
+    "@open-agent-toolkit/control-plane": "0.1.6"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",