forge-cc 1.0.2 → 2.0.0

package/dist/graph/schemas.d.ts

@@ -0,0 +1,215 @@
+import { z } from "zod";
+export declare const requirementStatusEnum: z.ZodEnum<["pending", "in_progress", "complete", "discovered", "rejected"]>;
+export declare const requirementFilesSchema: z.ZodObject<{
+    creates: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    modifies: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    creates: string[];
+    modifies: string[];
+}, {
+    creates?: string[] | undefined;
+    modifies?: string[] | undefined;
+}>;
+/** Validates YAML frontmatter of a requirement .md file. */
+export declare const requirementFrontmatterSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    dependsOn: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    files: z.ZodDefault<z.ZodObject<{
+        creates: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        modifies: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        creates: string[];
+        modifies: string[];
+    }, {
+        creates?: string[] | undefined;
+        modifies?: string[] | undefined;
+    }>>;
+    acceptance: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    title: string;
+    files: {
+        creates: string[];
+        modifies: string[];
+    };
+    acceptance: string[];
+    dependsOn?: string[] | undefined;
+}, {
+    id: string;
+    title: string;
+    acceptance: string[];
+    dependsOn?: string[] | undefined;
+    files?: {
+        creates?: string[] | undefined;
+        modifies?: string[] | undefined;
+    } | undefined;
+}>;
+/** Validates a single requirement entry in _index.yaml. */
+export declare const requirementMetaSchema: z.ZodObject<{
+    group: z.ZodString;
+    status: z.ZodEnum<["pending", "in_progress", "complete", "discovered", "rejected"]>;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    priority: z.ZodDefault<z.ZodNumber>;
+    linearIssueId: z.ZodOptional<z.ZodString>;
+    completedAt: z.ZodOptional<z.ZodString>;
+    discoveredBy: z.ZodOptional<z.ZodString>;
+    rejectedReason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "in_progress" | "complete" | "discovered" | "rejected";
+    dependsOn: string[];
+    group: string;
+    priority: number;
+    linearIssueId?: string | undefined;
+    completedAt?: string | undefined;
+    discoveredBy?: string | undefined;
+    rejectedReason?: string | undefined;
+}, {
+    status: "pending" | "in_progress" | "complete" | "discovered" | "rejected";
+    group: string;
+    dependsOn?: string[] | undefined;
+    priority?: number | undefined;
+    linearIssueId?: string | undefined;
+    completedAt?: string | undefined;
+    discoveredBy?: string | undefined;
+    rejectedReason?: string | undefined;
+}>;
+/** Validates a group definition in _index.yaml. */
+export declare const groupDefSchema: z.ZodObject<{
+    name: z.ZodString;
+    order: z.ZodOptional<z.ZodNumber>;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    linearMilestoneId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    dependsOn: string[];
+    name: string;
+    order?: number | undefined;
+    linearMilestoneId?: string | undefined;
+}, {
+    name: string;
+    dependsOn?: string[] | undefined;
+    order?: number | undefined;
+    linearMilestoneId?: string | undefined;
+}>;
+/** Validates the linear config block in _index.yaml. */
+export declare const linearConfigSchema: z.ZodObject<{
+    projectId: z.ZodString;
+    teamId: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    projectId: string;
+    teamId: string;
+}, {
+    projectId: string;
+    teamId: string;
+}>;
+/** Validates the full _index.yaml structure. */
+export declare const graphIndexSchema: z.ZodObject<{
+    project: z.ZodString;
+    slug: z.ZodString;
+    branch: z.ZodString;
+    createdAt: z.ZodString;
+    linear: z.ZodOptional<z.ZodObject<{
+        projectId: z.ZodString;
+        teamId: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        projectId: string;
+        teamId: string;
+    }, {
+        projectId: string;
+        teamId: string;
+    }>>;
+    groups: z.ZodRecord<z.ZodString, z.ZodObject<{
+        name: z.ZodString;
+        order: z.ZodOptional<z.ZodNumber>;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        linearMilestoneId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        dependsOn: string[];
+        name: string;
+        order?: number | undefined;
+        linearMilestoneId?: string | undefined;
+    }, {
+        name: string;
+        dependsOn?: string[] | undefined;
+        order?: number | undefined;
+        linearMilestoneId?: string | undefined;
+    }>>;
+    requirements: z.ZodRecord<z.ZodString, z.ZodObject<{
+        group: z.ZodString;
+        status: z.ZodEnum<["pending", "in_progress", "complete", "discovered", "rejected"]>;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        priority: z.ZodDefault<z.ZodNumber>;
+        linearIssueId: z.ZodOptional<z.ZodString>;
+        completedAt: z.ZodOptional<z.ZodString>;
+        discoveredBy: z.ZodOptional<z.ZodString>;
+        rejectedReason: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "in_progress" | "complete" | "discovered" | "rejected";
+        dependsOn: string[];
+        group: string;
+        priority: number;
+        linearIssueId?: string | undefined;
+        completedAt?: string | undefined;
+        discoveredBy?: string | undefined;
+        rejectedReason?: string | undefined;
+    }, {
+        status: "pending" | "in_progress" | "complete" | "discovered" | "rejected";
+        group: string;
+        dependsOn?: string[] | undefined;
+        priority?: number | undefined;
+        linearIssueId?: string | undefined;
+        completedAt?: string | undefined;
+        discoveredBy?: string | undefined;
+        rejectedReason?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    project: string;
+    slug: string;
+    branch: string;
+    createdAt: string;
+    groups: Record<string, {
+        dependsOn: string[];
+        name: string;
+        order?: number | undefined;
+        linearMilestoneId?: string | undefined;
+    }>;
+    requirements: Record<string, {
+        status: "pending" | "in_progress" | "complete" | "discovered" | "rejected";
+        dependsOn: string[];
+        group: string;
+        priority: number;
+        linearIssueId?: string | undefined;
+        completedAt?: string | undefined;
+        discoveredBy?: string | undefined;
+        rejectedReason?: string | undefined;
+    }>;
+    linear?: {
+        projectId: string;
+        teamId: string;
+    } | undefined;
+}, {
+    project: string;
+    slug: string;
+    branch: string;
+    createdAt: string;
+    groups: Record<string, {
+        name: string;
+        dependsOn?: string[] | undefined;
+        order?: number | undefined;
+        linearMilestoneId?: string | undefined;
+    }>;
+    requirements: Record<string, {
+        status: "pending" | "in_progress" | "complete" | "discovered" | "rejected";
+        group: string;
+        dependsOn?: string[] | undefined;
+        priority?: number | undefined;
+        linearIssueId?: string | undefined;
+        completedAt?: string | undefined;
+        discoveredBy?: string | undefined;
+        rejectedReason?: string | undefined;
+    }>;
+    linear?: {
+        projectId: string;
+        teamId: string;
+    } | undefined;
+}>;

package/dist/graph/schemas.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+export const requirementStatusEnum = z.enum([
+    "pending",
+    "in_progress",
+    "complete",
+    "discovered",
+    "rejected",
+]);
+export const requirementFilesSchema = z.object({
+    creates: z.array(z.string()).default([]),
+    modifies: z.array(z.string()).default([]),
+});
+/** Validates YAML frontmatter of a requirement .md file. */
+export const requirementFrontmatterSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    dependsOn: z.array(z.string()).optional(),
+    files: requirementFilesSchema.default({ creates: [], modifies: [] }),
+    acceptance: z.array(z.string()).min(1),
+});
+/** Validates a single requirement entry in _index.yaml. */
+export const requirementMetaSchema = z.object({
+    group: z.string().min(1),
+    status: requirementStatusEnum,
+    dependsOn: z.array(z.string()).default([]),
+    priority: z.number().int().default(0),
+    linearIssueId: z.string().optional(),
+    completedAt: z.string().optional(),
+    discoveredBy: z.string().optional(),
+    rejectedReason: z.string().optional(),
+});
+/** Validates a group definition in _index.yaml. */
+export const groupDefSchema = z.object({
+    name: z.string().min(1),
+    order: z.number().int().positive().optional(),
+    dependsOn: z.array(z.string()).default([]),
+    linearMilestoneId: z.string().optional(),
+});
+/** Validates the linear config block in _index.yaml. */
+export const linearConfigSchema = z.object({
+    projectId: z.string().min(1),
+    teamId: z.string().min(1),
+});
+/** Validates the full _index.yaml structure. */
+export const graphIndexSchema = z.object({
+    project: z.string().min(1),
+    slug: z.string().min(1),
+    branch: z.string().min(1),
+    createdAt: z.string().min(1),
+    linear: linearConfigSchema.optional(),
+    groups: z.record(z.string(), groupDefSchema),
+    requirements: z.record(z.string(), requirementMetaSchema),
+});
+//# sourceMappingURL=schemas.js.map

package/dist/graph/schemas.js.map

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

package/dist/graph/types.d.ts

@@ -0,0 +1,109 @@
+/** Requirement status lifecycle. */
+export type RequirementStatus = "pending" | "in_progress" | "complete" | "discovered" | "rejected";
+/** Scope declaration: which files a requirement creates or modifies. */
+export interface RequirementFiles {
+    creates: string[];
+    modifies: string[];
+}
+/** Requirement content parsed from a .md file in requirements/. */
+export interface Requirement {
+    /** Unique identifier. Must match key in GraphIndex.requirements. */
+    id: string;
+    /** Human-readable title. */
+    title: string;
+    /** Informational mirror of dependsOn from the index. For human readability only — the graph reader ignores this; the index is authoritative. */
+    dependsOn?: string[];
+    /** File scope declaration. Best-effort estimates from spec time. */
+    files: RequirementFiles;
+    /** Acceptance criteria — each item is a testable statement. */
+    acceptance: string[];
+    /** Full markdown body below the YAML frontmatter. */
+    body: string;
+}
+/** Requirement metadata stored in _index.yaml. */
+export interface RequirementMeta {
+    /** Key into GraphIndex.groups. */
+    group: string;
+    /** Current lifecycle status. */
+    status: RequirementStatus;
+    /** Requirement IDs that must be complete before this one starts. */
+    dependsOn: string[];
+    /** Scheduling priority. Higher = scheduled first. Default 0. */
+    priority?: number;
+    /** Linear issue UUID. */
+    linearIssueId?: string;
+    /** ISO 8601 timestamp — set when status transitions to complete. */
+    completedAt?: string;
+    /** Agent name — set when an agent creates a discovered requirement. */
+    discoveredBy?: string;
+    /** Reason — set when a discovered requirement is rejected. */
+    rejectedReason?: string;
+}
+/** Group definition — organizational grouping that replaces milestones. */
+export interface GroupDef {
+    /** Human-readable group name. */
+    name: string;
+    /** Tie-breaker for independent groups. Primary order is derived from the dependency DAG. */
+    order?: number;
+    /** Group keys that must fully complete before this group starts. */
+    dependsOn?: string[];
+    /** Linear ProjectMilestone UUID. */
+    linearMilestoneId?: string;
+}
+/** Linear integration configuration. */
+export interface LinearConfig {
+    /** Linear project UUID. */
+    projectId: string;
+    /** Linear team UUID. */
+    teamId: string;
+}
+/** Full _index.yaml structure — single source of truth for graph metadata. */
+export interface GraphIndex {
+    /** Human-readable project name. */
+    project: string;
+    /** URL-safe identifier, used for directory naming. */
+    slug: string;
+    /** Git feature branch name. */
+    branch: string;
+    /** ISO 8601 creation date. */
+    createdAt: string;
+    /** Linear integration config. Absent if Linear is not configured. */
+    linear?: LinearConfig;
+    /** Execution groups (organizational, replaces milestones). */
+    groups: Record<string, GroupDef>;
+    /** All requirement metadata. Keyed by requirement ID. */
+    requirements: Record<string, RequirementMeta>;
+}
+/** Resolved requirement = content + metadata joined from file + index. */
+export interface ResolvedRequirement {
+    /** Requirement content from the .md file. */
+    content: Requirement;
+    /** Requirement metadata from _index.yaml. */
+    meta: RequirementMeta;
+}
+/** The full project graph — index + overview + all requirement content. */
+export interface ProjectGraph {
+    /** Parsed _index.yaml. */
+    index: GraphIndex;
+    /** Raw markdown content of overview.md. */
+    overview: string;
+    /** Requirement content keyed by ID. */
+    requirements: Map<string, Requirement>;
+}
+/** Structural validation error. */
+export interface ValidationError {
+    type: "cycle" | "dangling_dep" | "missing_file" | "orphan_requirement" | "unknown_group" | "duplicate_id" | "schema_error" | "file_conflict";
+    message: string;
+    /** Contextual data — varies by error type. */
+    context: Record<string, unknown>;
+}
+/** Group completion summary. */
+export interface GroupStatus {
+    total: number;
+    complete: number;
+    inProgress: number;
+    pending: number;
+    discovered: number;
+    rejected: number;
+    isComplete: boolean;
+}

package/dist/graph/types.js

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

package/dist/graph/types.js.map

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

package/dist/graph/validator.d.ts

@@ -0,0 +1,32 @@
+import type { ProjectGraph, GraphIndex, Requirement, ValidationError } from "./types.js";
+/**
+ * Run all structural validation checks on a project graph.
+ * Returns all errors found (does not short-circuit on first error).
+ */
+export declare function validateGraph(graph: ProjectGraph): ValidationError[];
+/**
+ * Detect cycles in the requirement and group dependency graphs.
+ * Returns the cycle path if found, null if acyclic.
+ */
+export declare function detectCycles(index: GraphIndex): string[] | null;
+/**
+ * Find all dangling dependency edges — references to IDs that don't exist.
+ */
+export declare function findDanglingEdges(index: GraphIndex): Array<{
+    from: string;
+    to: string;
+    level: "requirement" | "group";
+}>;
+/**
+ * Find orphan requirements — files in the Map that aren't tracked in the index.
+ */
+export declare function findOrphans(graph: ProjectGraph): string[];
+/**
+ * Find file conflicts — files touched by multiple requirements that could run in parallel.
+ * Two requirements can run in parallel if they are in the same group and neither
+ * directly depends on the other.
+ */
+export declare function findFileConflicts(requirements: Map<string, Requirement>, index: GraphIndex): Array<{
+    file: string;
+    requirements: string[];
+}>;

package/dist/graph/validator.js

@@ -0,0 +1,253 @@
+/**
+ * Run all structural validation checks on a project graph.
+ * Returns all errors found (does not short-circuit on first error).
+ */
+export function validateGraph(graph) {
+    const errors = [];
+    // Dependency cycles
+    const reqCycle = detectCyclesInRequirements(graph.index);
+    if (reqCycle) {
+        errors.push({
+            type: "cycle",
+            message: `Requirement dependency cycle: ${reqCycle.join(" → ")}`,
+            context: { cycle: reqCycle, level: "requirement" },
+        });
+    }
+    const groupCycle = detectCyclesInGroups(graph.index);
+    if (groupCycle) {
+        errors.push({
+            type: "cycle",
+            message: `Group dependency cycle: ${groupCycle.join(" → ")}`,
+            context: { cycle: groupCycle, level: "group" },
+        });
+    }
+    // Dangling edges
+    for (const edge of findDanglingEdges(graph.index)) {
+        errors.push({
+            type: "dangling_dep",
+            message: `${edge.level} "${edge.from}" depends on non-existent ${edge.level} "${edge.to}"`,
+            context: edge,
+        });
+    }
+    // Missing files: in index but not in requirements Map
+    for (const id of Object.keys(graph.index.requirements)) {
+        if (!graph.requirements.has(id)) {
+            errors.push({
+                type: "missing_file",
+                message: `Requirement "${id}" is in the index but has no matching .md file`,
+                context: { id },
+            });
+        }
+    }
+    // Orphan files: in requirements Map but not in index
+    for (const id of findOrphans(graph)) {
+        errors.push({
+            type: "orphan_requirement",
+            message: `Requirement file "${id}" exists but is not tracked in the index`,
+            context: { id },
+        });
+    }
+    // Unknown groups
+    for (const [id, meta] of Object.entries(graph.index.requirements)) {
+        if (!(meta.group in graph.index.groups)) {
+            errors.push({
+                type: "unknown_group",
+                message: `Requirement "${id}" references unknown group "${meta.group}"`,
+                context: { id, group: meta.group },
+            });
+        }
+    }
+    // File conflicts
+    for (const conflict of findFileConflicts(graph.requirements, graph.index)) {
+        errors.push({
+            type: "file_conflict",
+            message: `File "${conflict.file}" is touched by multiple parallelizable requirements: ${conflict.requirements.join(", ")}`,
+            context: conflict,
+        });
+    }
+    return errors;
+}
+/**
+ * Detect cycles in the requirement and group dependency graphs.
+ * Returns the cycle path if found, null if acyclic.
+ */
+export function detectCycles(index) {
+    return detectCyclesInRequirements(index) ?? detectCyclesInGroups(index);
+}
+/** DFS cycle detection on the requirement dependency graph. */
+function detectCyclesInRequirements(index) {
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map();
+    for (const id of Object.keys(index.requirements)) {
+        color.set(id, WHITE);
+    }
+    for (const id of Object.keys(index.requirements)) {
+        if (color.get(id) === WHITE) {
+            const cycle = dfsVisit(id, color, (node) => index.requirements[node]?.dependsOn ?? []);
+            if (cycle)
+                return cycle;
+        }
+    }
+    return null;
+}
+/** DFS cycle detection on the group dependency graph. */
+function detectCyclesInGroups(index) {
+    const WHITE = 0, GRAY = 1, BLACK = 2;
+    const color = new Map();
+    for (const key of Object.keys(index.groups)) {
+        color.set(key, WHITE);
+    }
+    for (const key of Object.keys(index.groups)) {
+        if (color.get(key) === WHITE) {
+            const cycle = dfsVisit(key, color, (node) => index.groups[node]?.dependsOn ?? []);
+            if (cycle)
+                return cycle;
+        }
+    }
+    return null;
+}
+/**
+ * Generic DFS visit with gray-node cycle detection.
+ * Returns the cycle path when a back-edge is found, null otherwise.
+ */
+function dfsVisit(node, color, getNeighbors, path = []) {
+    const GRAY = 1, BLACK = 2;
+    color.set(node, GRAY);
+    path.push(node);
+    for (const neighbor of getNeighbors(node)) {
+        if (color.get(neighbor) === GRAY) {
+            // Found cycle — extract the cycle portion of the path
+            const cycleStart = path.indexOf(neighbor);
+            return [...path.slice(cycleStart), neighbor];
+        }
+        if (color.get(neighbor) !== BLACK && color.has(neighbor)) {
+            const cycle = dfsVisit(neighbor, color, getNeighbors, path);
+            if (cycle)
+                return cycle;
+        }
+    }
+    path.pop();
+    color.set(node, BLACK);
+    return null;
+}
+/**
+ * Find all dangling dependency edges — references to IDs that don't exist.
+ */
+export function findDanglingEdges(index) {
+    const dangling = [];
+    // Requirement-level dangling edges
+    for (const [id, meta] of Object.entries(index.requirements)) {
+        for (const dep of meta.dependsOn) {
+            if (!(dep in index.requirements)) {
+                dangling.push({ from: id, to: dep, level: "requirement" });
+            }
+        }
+    }
+    // Group-level dangling edges
+    for (const [key, group] of Object.entries(index.groups)) {
+        for (const dep of group.dependsOn ?? []) {
+            if (!(dep in index.groups)) {
+                dangling.push({ from: key, to: dep, level: "group" });
+            }
+        }
+    }
+    return dangling;
+}
+/**
+ * Find orphan requirements — files in the Map that aren't tracked in the index.
+ */
+export function findOrphans(graph) {
+    const orphans = [];
+    for (const id of graph.requirements.keys()) {
+        if (!(id in graph.index.requirements)) {
+            orphans.push(id);
+        }
+    }
+    return orphans;
+}
+/**
+ * Find file conflicts — files touched by multiple requirements that could run in parallel.
+ * Two requirements can run in parallel if they are in the same group and neither
+ * directly depends on the other.
+ */
+export function findFileConflicts(requirements, index) {
+    // Build a map of file → requirement IDs that touch it
+    const fileToReqs = new Map();
+    for (const [id, req] of requirements) {
+        // Only consider requirements that are in the index
+        if (!(id in index.requirements))
+            continue;
+        const allFiles = [...req.files.creates, ...req.files.modifies];
+        for (const file of allFiles) {
+            const existing = fileToReqs.get(file);
+            if (existing) {
+                existing.push(id);
+            }
+            else {
+                fileToReqs.set(file, [id]);
+            }
+        }
+    }
+    const conflicts = [];
+    for (const [file, reqIds] of fileToReqs) {
+        if (reqIds.length < 2)
+            continue;
+        // Filter to only those that could run in parallel:
+        // same group, no direct dependency between them
+        const parallelizable = findParallelizable(reqIds, index);
+        if (parallelizable.length >= 2) {
+            conflicts.push({ file, requirements: parallelizable });
+        }
+    }
+    return conflicts;
+}
+/**
+ * Given a set of requirement IDs, return those that could theoretically run in parallel.
+ * Requirements can run in parallel if they share the same group and neither
+ * directly depends on the other.
+ */
+function findParallelizable(reqIds, index) {
+    // Group requirements by their group
+    const byGroup = new Map();
+    for (const id of reqIds) {
+        const meta = index.requirements[id];
+        if (!meta)
+            continue;
+        const existing = byGroup.get(meta.group);
+        if (existing) {
+            existing.push(id);
+        }
+        else {
+            byGroup.set(meta.group, [id]);
+        }
+    }
+    const result = [];
+    for (const groupReqs of byGroup.values()) {
+        if (groupReqs.length < 2)
+            continue;
+        // Build direct dependency set for fast lookup
+        const depSets = new Map();
+        for (const id of groupReqs) {
+            depSets.set(id, new Set(index.requirements[id]?.dependsOn ?? []));
+        }
+        // Find pairs that have no direct dependency
+        for (const id of groupReqs) {
+            let isParallel = false;
+            for (const otherId of groupReqs) {
+                if (id === otherId)
+                    continue;
+                const idDeps = depSets.get(id);
+                const otherDeps = depSets.get(otherId);
+                if (!idDeps.has(otherId) && !otherDeps.has(id)) {
+                    isParallel = true;
+                    break;
+                }
+            }
+            if (isParallel) {
+                result.push(id);
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=validator.js.map