proposal: add instruction loader and schema restructure (Slice 3)

openspec/changes/add-instruction-loader/design.md

@@ -0,0 +1,149 @@
+## Context
+
+This is Slice 3 of the artifact-graph POC. We have:
+- `ArtifactGraph` class with graph operations (Slice 1)
+- `detectCompleted()` for filesystem-based state detection (Slice 1)
+- `resolveSchema()` for XDG schema resolution (Slice 1)
+- `createChange()` and `validateChangeName()` utilities (Slice 2)
+
+After `restructure-schema-directories` is implemented, schemas will be self-contained directories:
+```
+schemas/<name>/
+├── schema.yaml
+└── templates/
+    └── *.md
+```
+
+This proposal adds template loading and instruction enrichment on top of that structure.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Load templates from schema directories
+- Enrich templates with change-specific context (dependency status)
+- Format change status for CLI output
+
+**Non-Goals:**
+- Template authoring UI
+- Dynamic template compilation/execution
+- Caching (keep it stateless like the rest)
+
+## Decisions
+
+### 1. Pure functions over classes
+
+Follow the pattern in `resolver.ts` and `state.ts`. Use a simple `ChangeContext` interface with pure functions:
+
+```typescript
+interface ChangeContext {
+  changeName: string;
+  changeDir: string;
+  schemaName: string;
+  graph: ArtifactGraph;
+  completed: CompletedSet;
+}
+
+function loadChangeContext(projectRoot: string, changeName: string, schemaName?: string): ChangeContext
+function loadTemplate(schemaName: string, templatePath: string): string
+function getInstructions(artifactId: string, context: ChangeContext): string
+function formatStatus(context: ChangeContext): string
+```
+
+**Why:** Matches existing codebase patterns. Easier to test. No hidden state.
+
+### 2. Template resolution from schema directory
+
+Templates are loaded from the schema's `templates/` subdirectory:
+
+```typescript
+function loadTemplate(schemaName: string, templatePath: string): string {
+  const schemaDir = getSchemaDir(schemaName);  // From resolver.ts
+  const fullPath = path.join(schemaDir, 'templates', templatePath);
+  return fs.readFileSync(fullPath, 'utf-8');
+}
+```
+
+Resolution is handled by `getSchemaDir()` which already checks user override → package built-in.
+
+**Why:** Leverages existing schema resolution. Templates are co-located with schemas.
+
+### 3. Template path from artifact definition
+
+The artifact's `template` field is a path relative to the schema's `templates/` directory:
+
+```yaml
+artifacts:
+  - id: proposal
+    template: "proposal.md"  # → schemas/<schema>/templates/proposal.md
+```
+
+**Why:** Explicit, simple, no magic.
+
+### 4. Minimal context injection
+
+Templates are markdown. Injection prepends a header section with context:
+
+```markdown
+---
+change: add-auth
+artifact: proposal
+schema: spec-driven
+output: openspec/changes/add-auth/proposal.md
+---
+
+## Dependencies
+- [x] (none - this is a root artifact)
+
+## Next Steps
+After creating this artifact, you can work on: design, specs
+
+---
+
+[original template content...]
+```
+
+**Why:** Simple string concatenation. No template engine dependency. Clear separation.
+
+### 5. Status output format
+
+```markdown
+## Change: add-auth (spec-driven)
+
+| Artifact | Status | Output |
+|----------|--------|--------|
+| proposal | done | proposal.md |
+| specs | ready | specs/*.md |
+| design | blocked (needs: proposal) | design.md |
+| tasks | blocked (needs: specs, design) | tasks.md |
+```
+
+**Why:** Markdown table is readable in terminal and docs. Matches CLI output style.
+
+## File Structure
+
+```
+src/core/artifact-graph/
+├── index.ts              # Add new exports
+├── template.ts           # NEW: Template loading
+├── context.ts            # NEW: ChangeContext loading
+└── instructions.ts       # NEW: Enrichment and formatting
+```
+
+## Risks / Trade-offs
+
+**Dependency on restructure-schema-directories:**
+- This proposal requires the schema restructure to be done first
+- Mitigation: Clear dependency documented, implement in order
+
+**No template engine:**
+- Pro: Zero dependencies, simple code
+- Con: Limited expressiveness
+- Mitigation: Current use case only needs static templates + header injection
+
+## Migration Plan
+
+N/A - new capability, no existing code to migrate.
+
+## Open Questions
+
+None.

openspec/changes/add-instruction-loader/proposal.md

@@ -0,0 +1,20 @@
+## Why
+
+Slice 1 (artifact-graph) provides graph operations and state detection. Slice 2 (change-utils) provides change creation. We now need the ability to load templates for artifacts and enrich them with change-specific context so users/agents know what to create next.
+
+## What Changes
+
+- Add template resolution from schema directories (uses structure from `restructure-schema-directories`)
+- Add instruction enrichment that injects change context into templates
+- Add status formatting for CLI output
+- New `instruction-loader` capability
+
+## Dependencies
+
+- Requires `restructure-schema-directories` to be implemented first (schemas as directories with co-located templates)
+
+## Impact
+
+- Affected specs: New `instruction-loader` spec
+- Affected code: `src/core/artifact-graph/` (new files)
+- Builds on: `artifact-graph` (Slice 1), uses `ArtifactGraph`, `detectCompleted`, `resolveSchema`

openspec/changes/add-instruction-loader/specs/instruction-loader/spec.md

@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: Template Loading
+The system SHALL load templates from schema directories.
+
+#### Scenario: Template loaded from schema directory
+- **WHEN** `loadTemplate(schemaName, templatePath)` is called
+- **THEN** the system loads the template from `schemas/<schemaName>/templates/<templatePath>`
+
+#### Scenario: Template not found
+- **WHEN** a template file does not exist in the schema's templates directory
+- **THEN** the system throws an error with the template path
+
+### Requirement: Change Context Loading
+The system SHALL load change context combining graph and completion state.
+
+#### Scenario: Load context for existing change
+- **WHEN** `loadChangeContext(projectRoot, changeName)` is called for an existing change
+- **THEN** the system returns a context with graph, completed set, schema name, and change info
+
+#### Scenario: Load context with custom schema
+- **WHEN** `loadChangeContext(projectRoot, changeName, schemaName)` is called
+- **THEN** the system uses the specified schema instead of default
+
+#### Scenario: Load context for missing change
+- **WHEN** `loadChangeContext` is called for a non-existent change directory
+- **THEN** the system returns context with empty completed set
+
+### Requirement: Instruction Enrichment
+The system SHALL enrich templates with change-specific context.
+
+#### Scenario: Header with change info
+- **WHEN** instructions are generated for an artifact
+- **THEN** the output includes change name, artifact ID, schema name, and output path
+
+#### Scenario: Dependency status shown
+- **WHEN** an artifact has dependencies
+- **THEN** the output shows each dependency with completion status (done/missing)
+
+#### Scenario: Next steps shown
+- **WHEN** instructions are generated
+- **THEN** the output includes which artifacts become available after this one
+
+#### Scenario: Root artifact dependencies
+- **WHEN** an artifact has no dependencies
+- **THEN** the dependency section indicates this is a root artifact
+
+### Requirement: Status Formatting
+The system SHALL format change status as readable output.
+
+#### Scenario: Format complete change
+- **WHEN** all artifacts are completed
+- **THEN** status shows all artifacts as "done"
+
+#### Scenario: Format partial change
+- **WHEN** some artifacts are completed
+- **THEN** status shows completed as "done", ready as "ready", blocked as "blocked"
+
+#### Scenario: Show blocked dependencies
+- **WHEN** an artifact is blocked
+- **THEN** status shows which dependencies are missing
+
+#### Scenario: Show output paths
+- **WHEN** status is formatted
+- **THEN** each artifact shows its output path pattern

openspec/changes/add-instruction-loader/tasks.md

@@ -0,0 +1,34 @@
+## 1. Template Loading
+
+- [ ] 1.1 Create `src/core/artifact-graph/template.ts`
+- [ ] 1.2 Implement `loadTemplate(schemaName, templatePath)` using schema directory structure
+- [ ] 1.3 Add tests for template loading from schema directory
+- [ ] 1.4 Add tests for error when template not found
+
+## 2. Change Context
+
+- [ ] 2.1 Create `src/core/artifact-graph/context.ts`
+- [ ] 2.2 Define `ChangeContext` interface
+- [ ] 2.3 Implement `loadChangeContext()` function
+- [ ] 2.4 Add tests for context loading with existing change
+- [ ] 2.5 Add tests for context loading with missing change directory
+
+## 3. Instruction Enrichment
+
+- [ ] 3.1 Create `src/core/artifact-graph/instructions.ts`
+- [ ] 3.2 Implement `getInstructions()` with header injection
+- [ ] 3.3 Add dependency status formatting (done/missing)
+- [ ] 3.4 Add next steps calculation
+- [ ] 3.5 Add tests for enrichment output
+
+## 4. Status Formatting
+
+- [ ] 4.1 Implement `formatStatus()` function in instructions.ts
+- [ ] 4.2 Format as markdown table with status and output path
+- [ ] 4.3 Show blocked dependencies
+- [ ] 4.4 Add tests for status formatting
+
+## 5. Integration
+
+- [ ] 5.1 Export new functions from `src/core/artifact-graph/index.ts`
+- [ ] 5.2 Ensure all tests pass