# Artifact Graph Specification

> Generated by openlore on 2025-01-30
> Source files: src/core/artifact-graph/types.ts, src/core/artifact-graph/schema.ts, src/core/artifact-graph/resolver.ts, src/core/artifact-graph/graph.ts

## Purpose

Manages artifact dependencies and workflow ordering for spec-driven development. Provides schema resolution from multiple locations, dependency graph validation, and instruction loading with context injection.

## Entities

### Artifact

| Property | Type | Description |
|----------|------|-------------|
| id | string | Unique artifact identifier |
| generates | string | Output file/directory pattern |
| template | string | Template name for generation |
| instruction | string | AI instruction content |
| requires | string[] | IDs of dependent artifacts |

### SchemaYaml

| Property | Type | Description |
|----------|------|-------------|
| name | string | Schema name |
| version | number | Schema version |
| artifacts | Artifact[] | Ordered artifact definitions |

### ResolvedSchema

| Property | Type | Description |
|----------|------|-------------|
| schema | SchemaYaml | Parsed schema content |
| source | 'project' \| 'user' \| 'package' | Resolution location |
| path | string | File system path |

## Requirements

### Requirement: SchemaResolution

The system SHALL resolve schemas from multiple locations with defined precedence: project > user > package.

#### Scenario: ProjectSchemaOverride
- **GIVEN** a schema "custom" exists in both project and package locations
- **WHEN** schema resolution is performed
- **THEN** the project schema is returned
- **AND** the source is marked as "project"

#### Scenario: FallbackToPackage
- **GIVEN** a schema "spec-driven" only exists in package location
- **WHEN** schema resolution is performed
- **THEN** the package schema is returned
- **AND** the source is marked as "package"

#### Scenario: SchemaNotFound
- **GIVEN** a requested schema "nonexistent" is not in any location
- **WHEN** schema resolution is attempted
- **THEN** an error is returned indicating schema not found

### Requirement: DependencyValidation

The system SHALL validate artifact dependency graphs for cycles and missing dependencies.

#### Scenario: ValidDAG
- **GIVEN** artifacts A → B → C with no cycles
- **WHEN** graph validation is performed
- **THEN** validation passes
- **AND** topological order is [A, B, C]

#### Scenario: CycleDetection
- **GIVEN** artifacts A → B → C → A forming a cycle
- **WHEN** graph validation is performed
- **THEN** validation fails with "CYCLE_DETECTED" error
- **AND** the cycle path is reported

#### Scenario: MissingDependency
- **GIVEN** artifact A requires artifact "missing" which doesn't exist
- **WHEN** graph validation is performed
- **THEN** validation fails with "MISSING_DEPENDENCY" error

### Requirement: TopologicalOrdering

The system SHALL provide topologically sorted artifact order for workflow execution.

#### Scenario: LinearDependencies
- **GIVEN** artifacts: proposal → specs → design → tasks
- **WHEN** topological sort is computed
- **THEN** order is [proposal, specs, design, tasks]

#### Scenario: ParallelArtifacts
- **GIVEN** specs and design both only require proposal
- **WHEN** topological sort is computed
- **THEN** proposal comes first
- **AND** specs and design can be in either order after proposal

### Requirement: InstructionLoading

The system SHALL load artifact instructions with context injection and dependency content.

#### Scenario: ContextInjection
- **GIVEN** project config with context field "This is an API project"
- **WHEN** instructions are loaded for an artifact
- **THEN** the context is injected into the instruction template

#### Scenario: DependencyContentInclusion
- **GIVEN** artifact "design" requires artifact "specs"
- **WHEN** instructions are loaded for "design"
- **THEN** the content of completed "specs" artifact is included

#### Scenario: RulesApplication
- **GIVEN** config.yaml has rules for "specs" artifact
- **WHEN** instructions are loaded for "specs"
- **THEN** the artifact-specific rules are appended

### Requirement: ArtifactStateTracking

The system SHALL track which artifacts have been completed for a change.

#### Scenario: CheckArtifactCompletion
- **GIVEN** a change with "proposal.md" file present
- **WHEN** artifact state is checked
- **THEN** "proposal" artifact is marked as complete

#### Scenario: IdentifyNextArtifact
- **GIVEN** "proposal" is complete but "specs" is not
- **WHEN** next artifact is requested
- **THEN** "specs" is returned as the next artifact to work on

### Requirement: SchemaVersioning

The system SHOULD support schema versioning for backwards compatibility.

#### Scenario: VersionMismatchWarning
- **GIVEN** a project using schema version 1
- **WHEN** package provides schema version 2
- **THEN** a warning is issued about version mismatch

## Technical Notes

- **Implementation**: `src/core/artifact-graph/schema.ts`, `src/core/artifact-graph/resolver.ts`, `src/core/artifact-graph/graph.ts`
- **Pattern**: Multi-location resolution with caching
- **Dependencies**: YAML parser for schema files