sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/changes/archive/2026-02-17-project-config/design.md

@@ -1,665 +0,0 @@
-# Design: Project Config
-
-## Context
-
-OpenSpec currently has a fixed schema resolution order:
-1. `--schema` CLI flag
-2. `.openspec.yaml` in change directory
-3. Hardcoded default: `"spec-driven"`
-
-This forces users who want project-level customization to fork entire schemas, even for simple additions like injecting tech stack context or adding artifact-specific rules.
-
-The proposal introduces `openspec/config.yaml` as a lightweight customization layer that sits between preset schemas and full forking. It allows teams to:
-- Set a default schema
-- Inject project context into all artifacts
-- Add per-artifact rules
-
-**Constraints:**
-- Must not break existing changes that lack config
-- Must maintain clean separation between "configure" (this) and "fork" (project-local-schemas)
-- Config is project-level only (no global/user-level config)
-
-**Key stakeholders:**
-- OpenSpec users who need light customization without forking
-- Teams sharing workflow conventions via committed config
-
-## Goals / Non-Goals
-
-**Goals:**
-- Load and parse `openspec/config.yaml` using Zod schema
-- Use config's `schema` field as default in schema resolution
-- Inject `context` into all artifact instructions
-- Inject `rules` into matching artifact instructions only
-- Gracefully handle missing or invalid config (fallback to defaults)
-
-**Non-Goals:**
-- Structural changes to schemas (`skip`, `add`, inheritance) - those belong in fork path
-- File references for context (`context: ./file.md`) - start with strings
-- Global user-level config (XDG dirs, etc.)
-- Config management commands (`openspec config init`) - manual creation for now
-- Migration from old setups (no existing config to migrate from)
-
-## Decisions
-
-### 1. Config File Format: YAML vs JSON
-
-**Decision:** Use YAML (`.yaml` extension, support `.yml` alias)
-
-**Rationale:**
-- YAML supports multi-line strings naturally (`context: |`)
-- More readable for documentation-heavy content
-- Consistent with `.openspec.yaml` used in changes
-- Easy to parse with existing `yaml` library
-
-**Alternatives considered:**
-- JSON: More strict, but poor multi-line string UX
-- TOML: Less familiar to most users
-
-### 2. Config Location: Project Root vs openspec/ Directory
-
-**Decision:** `./openspec/config.yaml` (inside openspec directory)
-
-**Rationale:**
-- Co-located with `openspec/schemas/` (project-local-schemas)
-- Keeps project root clean
-- Natural namespace for OpenSpec configuration
-- Mirrors structure used by other tools (e.g., `.github/`)
-
-**Alternatives considered:**
-- `./openspec.config.yaml` in root: Pollutes root, less clear ownership
-- XDG config directories: Out of scope, no global config yet
-
-### 3. Context Injection: XML Tags vs Markdown Sections
-
-**Decision:** Use XML-style tags `<context>` and `<rules>`
-
-**Rationale:**
-- Clear delimiters that don't conflict with Markdown
-- Agents can easily parse structure
-- Matches existing patterns in the codebase for special sections
-
-**Example:**
-```xml
-<context>
-Tech stack: TypeScript, React
-</context>
-
-<rules>
-- Include rollback plan
-</rules>
-
-<template>
-## Summary
-...
-</template>
-```
-
-**Alternatives considered:**
-- Markdown headers: Conflicts with template content
-- Comments: Less visible to agents
-
-### 4. Schema Resolution: Insert Position
-
-**Decision:** Config's `schema` field goes between change metadata and hardcoded default
-
-**New resolution order:**
-1. `--schema` CLI flag (explicit override)
-2. `.openspec.yaml` in change directory (change-specific binding)
-3. **`openspec/config.yaml` schema field** (NEW - project default)
-4. `"spec-driven"` (hardcoded fallback)
-
-**Rationale:**
-- Preserves CLI and change-level overrides (most specific wins)
-- Makes config act as a "project default"
-- Backwards compatible (no existing configs to conflict with)
-
-### 5. Rules Validation: Strict vs Permissive
-
-**Decision:** Warn on unknown artifact IDs, don't error
-
-**Rationale:**
-- Future-proof: If schema adds new artifacts, old configs don't break
-- Dev experience: Typos show warnings, but don't halt workflow
-- User can fix incrementally
-
-**Example:**
-```yaml
-rules:
-  proposal: [...]
-  testplan: [...]  # Schema doesn't have this artifact → WARN, not ERROR
-```
-
-### 6. Error Handling: Config Parse Failures
-
-**Decision:** Log warning and fall back to defaults (don't halt commands)
-
-**Rationale:**
-- Syntax errors in config shouldn't break all of OpenSpec
-- User can fix config incrementally
-- Commands remain usable during config development
-
-**Warning message:**
-```
-⚠️  Failed to parse openspec/config.yaml: [error details]
-    Falling back to default schema (spec-driven)
-```
-
-## Implementation Plan
-
-### Phase 1: Core Types and Loading
-
-**File: `src/core/project-config.ts` (NEW)**
-
-```typescript
-import { z } from 'zod';
-import { readFileSync, existsSync } from 'fs';
-import { parse as parseYaml } from 'yaml';
-import { findProjectRoot } from '../utils/path-utils';
-
-/**
- * Zod schema for project configuration.
- *
- * Purpose:
- * 1. Documentation - clearly defines the config file structure
- * 2. Type safety - TypeScript infers ProjectConfig type from schema
- * 3. Runtime validation - uses safeParse() for resilient field-by-field validation
- *
- * Why Zod over manual validation:
- * - Helps understand OpenSpec's data interfaces at a glance
- * - Single source of truth for type and validation
- * - Consistent with other OpenSpec schemas
- */
-export const ProjectConfigSchema = z.object({
-  schema: z.string().min(1).describe('The workflow schema to use (e.g., "spec-driven", "tdd")'),
-  context: z.string().optional().describe('Project context injected into all artifact instructions'),
-  rules: z.record(
-    z.string(),
-    z.array(z.string())
-  ).optional().describe('Per-artifact rules, keyed by artifact ID'),
-});
-
-export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
-
-const MAX_CONTEXT_SIZE = 50 * 1024; // 50KB hard limit
-
-/**
- * Read and parse openspec/config.yaml from project root.
- * Uses resilient parsing - validates each field independently using Zod safeParse.
- * Returns null if file doesn't exist.
- * Returns partial config if some fields are invalid (with warnings).
- */
-export function readProjectConfig(): ProjectConfig | null {
-  const projectRoot = findProjectRoot();
-
-  // Try both .yaml and .yml, prefer .yaml
-  let configPath = path.join(projectRoot, 'openspec', 'config.yaml');
-  if (!existsSync(configPath)) {
-    configPath = path.join(projectRoot, 'openspec', 'config.yml');
-    if (!existsSync(configPath)) {
-      return null; // No config is OK
-    }
-  }
-
-  try {
-    const content = readFileSync(configPath, 'utf-8');
-    const raw = parseYaml(content);
-
-    if (!raw || typeof raw !== 'object') {
-      console.warn(`⚠️  openspec/config.yaml is not a valid YAML object`);
-      return null;
-    }
-
-    const config: Partial<ProjectConfig> = {};
-
-    // Parse schema field using Zod
-    const schemaField = z.string().min(1);
-    const schemaResult = schemaField.safeParse(raw.schema);
-    if (schemaResult.success) {
-      config.schema = schemaResult.data;
-    } else if (raw.schema !== undefined) {
-      console.warn(`⚠️  Invalid 'schema' field in config (must be non-empty string)`);
-    }
-
-    // Parse context field with size limit
-    if (raw.context !== undefined) {
-      const contextField = z.string();
-      const contextResult = contextField.safeParse(raw.context);
-
-      if (contextResult.success) {
-        const contextSize = Buffer.byteLength(contextResult.data, 'utf-8');
-        if (contextSize > MAX_CONTEXT_SIZE) {
-          console.warn(
-            `⚠️  Context too large (${(contextSize / 1024).toFixed(1)}KB, limit: ${MAX_CONTEXT_SIZE / 1024}KB)`
-          );
-          console.warn(`   Ignoring context field`);
-        } else {
-          config.context = contextResult.data;
-        }
-      } else {
-        console.warn(`⚠️  Invalid 'context' field in config (must be string)`);
-      }
-    }
-
-    // Parse rules field using Zod
-    if (raw.rules !== undefined) {
-      const rulesField = z.record(z.string(), z.array(z.string()));
-
-      // First check if it's an object structure
-      if (typeof raw.rules === 'object' && !Array.isArray(raw.rules)) {
-        const parsedRules: Record<string, string[]> = {};
-        let hasValidRules = false;
-
-        for (const [artifactId, rules] of Object.entries(raw.rules)) {
-          const rulesArrayResult = z.array(z.string()).safeParse(rules);
-
-          if (rulesArrayResult.success) {
-            // Filter out empty strings
-            const validRules = rulesArrayResult.data.filter(r => r.length > 0);
-            if (validRules.length > 0) {
-              parsedRules[artifactId] = validRules;
-              hasValidRules = true;
-            }
-            if (validRules.length < rulesArrayResult.data.length) {
-              console.warn(
-                `⚠️  Some rules for '${artifactId}' are empty strings, ignoring them`
-              );
-            }
-          } else {
-            console.warn(
-              `⚠️  Rules for '${artifactId}' must be an array of strings, ignoring this artifact's rules`
-            );
-          }
-        }
-
-        if (hasValidRules) {
-          config.rules = parsedRules;
-        }
-      } else {
-        console.warn(`⚠️  Invalid 'rules' field in config (must be object)`);
-      }
-    }
-
-    // Return partial config even if some fields failed
-    return Object.keys(config).length > 0 ? (config as ProjectConfig) : null;
-
-  } catch (error) {
-    console.warn(`⚠️  Failed to parse openspec/config.yaml:`, error);
-    return null;
-  }
-}
-
-/**
- * Validate artifact IDs in rules against a schema's artifacts.
- * Called during instruction loading (when schema is known).
- * Returns warnings for unknown artifact IDs.
- */
-export function validateConfigRules(
-  rules: Record<string, string[]>,
-  validArtifactIds: Set<string>,
-  schemaName: string
-): string[] {
-  const warnings: string[] = [];
-
-  for (const artifactId of Object.keys(rules)) {
-    if (!validArtifactIds.has(artifactId)) {
-      const validIds = Array.from(validArtifactIds).sort().join(', ');
-      warnings.push(
-        `Unknown artifact ID in rules: "${artifactId}". ` +
-        `Valid IDs for schema "${schemaName}": ${validIds}`
-      );
-    }
-  }
-
-  return warnings;
-}
-
-/**
- * Suggest valid schema names when user provides invalid schema.
- * Uses fuzzy matching to find similar names.
- */
-export function suggestSchemas(
-  invalidSchemaName: string,
-  availableSchemas: { name: string; isBuiltIn: boolean }[]
-): string {
-  // Simple fuzzy match: Levenshtein distance
-  function levenshtein(a: string, b: string): number {
-    const matrix: number[][] = [];
-    for (let i = 0; i <= b.length; i++) {
-      matrix[i] = [i];
-    }
-    for (let j = 0; j <= a.length; j++) {
-      matrix[0][j] = j;
-    }
-    for (let i = 1; i <= b.length; i++) {
-      for (let j = 1; j <= a.length; j++) {
-        if (b.charAt(i - 1) === a.charAt(j - 1)) {
-          matrix[i][j] = matrix[i - 1][j - 1];
-        } else {
-          matrix[i][j] = Math.min(
-            matrix[i - 1][j - 1] + 1,
-            matrix[i][j - 1] + 1,
-            matrix[i - 1][j] + 1
-          );
-        }
-      }
-    }
-    return matrix[b.length][a.length];
-  }
-
-  // Find closest matches (distance <= 3)
-  const suggestions = availableSchemas
-    .map(s => ({ ...s, distance: levenshtein(invalidSchemaName, s.name) }))
-    .filter(s => s.distance <= 3)
-    .sort((a, b) => a.distance - b.distance)
-    .slice(0, 3);
-
-  const builtIn = availableSchemas.filter(s => s.isBuiltIn).map(s => s.name);
-  const projectLocal = availableSchemas.filter(s => !s.isBuiltIn).map(s => s.name);
-
-  let message = `❌ Schema '${invalidSchemaName}' not found in openspec/config.yaml\n\n`;
-
-  if (suggestions.length > 0) {
-    message += `Did you mean one of these?\n`;
-    suggestions.forEach(s => {
-      const type = s.isBuiltIn ? 'built-in' : 'project-local';
-      message += `  - ${s.name} (${type})\n`;
-    });
-    message += '\n';
-  }
-
-  message += `Available schemas:\n`;
-  if (builtIn.length > 0) {
-    message += `  Built-in: ${builtIn.join(', ')}\n`;
-  }
-  if (projectLocal.length > 0) {
-    message += `  Project-local: ${projectLocal.join(', ')}\n`;
-  } else {
-    message += `  Project-local: (none found)\n`;
-  }
-
-  message += `\nFix: Edit openspec/config.yaml and change 'schema: ${invalidSchemaName}' to a valid schema name`;
-
-  return message;
-}
-```
-
-### Phase 2: Schema Resolution
-
-**File: `src/utils/change-metadata.ts`**
-
-Update `resolveSchemaForChange()` to check config:
-
-```typescript
-export function resolveSchemaForChange(
-  changeName: string,
-  cliSchema?: string
-): string {
-  // 1. CLI flag wins
-  if (cliSchema) {
-    return cliSchema;
-  }
-
-  // 2. Change metadata (.openspec.yaml)
-  const metadata = readChangeMetadata(changeName);
-  if (metadata?.schema) {
-    return metadata.schema;
-  }
-
-  // 3. Project config (NEW)
-  const projectConfig = readProjectConfig();
-  if (projectConfig?.schema) {
-    return projectConfig.schema;
-  }
-
-  // 4. Hardcoded default
-  return 'spec-driven';
-}
-```
-
-**File: `src/utils/change-utils.ts`**
-
-Update `createNewChange()` to use config schema:
-
-```typescript
-export function createNewChange(
-  changeName: string,
-  schema?: string
-): void {
-  // Use schema from config if not specified
-  const resolvedSchema = schema ?? readProjectConfig()?.schema ?? 'spec-driven';
-
-  // ... rest of change creation logic
-}
-```
-
-### Phase 3: Instruction Injection and Validation
-
-**File: `src/core/artifact-graph/instruction-loader.ts`**
-
-Update `loadInstructions()` to inject context, rules, and validate artifact IDs:
-
-```typescript
-// Session-level cache for validation warnings (avoid repeating same warnings)
-const shownWarnings = new Set<string>();
-
-export function loadInstructions(
-  changeName: string,
-  artifactId: string
-): InstructionOutput {
-  const projectConfig = readProjectConfig();
-
-  // Load base instructions from schema
-  const baseInstructions = loadSchemaInstructions(changeName, artifactId);
-  const schema = getSchemaForChange(changeName); // Assumes we have schema loaded
-
-  // Validate rules artifact IDs (only once per session)
-  if (projectConfig?.rules) {
-    const validArtifactIds = new Set(schema.artifacts.map(a => a.id));
-    const warnings = validateConfigRules(
-      projectConfig.rules,
-      validArtifactIds,
-      schema.name
-    );
-
-    // Show each unique warning only once per session
-    for (const warning of warnings) {
-      if (!shownWarnings.has(warning)) {
-        console.warn(`⚠️  ${warning}`);
-        shownWarnings.add(warning);
-      }
-    }
-  }
-
-  // Build enriched instruction with XML sections
-  let enrichedInstruction = '';
-
-  // Add context (all artifacts)
-  if (projectConfig?.context) {
-    enrichedInstruction += `<context>\n${projectConfig.context}\n</context>\n\n`;
-  }
-
-  // Add rules (only for matching artifact)
-  const rulesForArtifact = projectConfig?.rules?.[artifactId];
-  if (rulesForArtifact && rulesForArtifact.length > 0) {
-    enrichedInstruction += `<rules>\n`;
-    for (const rule of rulesForArtifact) {
-      enrichedInstruction += `- ${rule}\n`;
-    }
-    enrichedInstruction += `</rules>\n\n`;
-  }
-
-  // Add original template
-  enrichedInstruction += `<template>\n${baseInstructions.template}\n</template>`;
-
-  return {
-    ...baseInstructions,
-    instruction: enrichedInstruction,
-  };
-}
-```
-
-**Note on validation timing:** Rules are validated lazily during instruction loading (not at config load time) because:
-1. Schema isn't known at config load time (circular dependency)
-2. Warnings shown when user actually uses the feature (better UX)
-3. Validation warnings cached per session to avoid spam
-
-### Phase 4: Performance and Caching
-
-**Why config is read multiple times:**
-
-```typescript
-// Example: "openspec instructions proposal --change my-feature"
-
-// 1. Schema resolution (to know which schema to use)
-resolveSchemaForChange('my-feature')
-  → readProjectConfig()  // Read #1
-
-// 2. Instruction loading (to inject context and rules)
-loadInstructions('my-feature', 'proposal')
-  → readProjectConfig()  // Read #2
-
-// Result: Config read twice per command
-// More complex commands may read 3-5 times
-```
-
-**Performance Strategy:**
-
-V1 approach: No caching, read config fresh each time
-- Simpler implementation
-- No cache invalidation complexity
-- Acceptable if config reads are fast enough
-
-**Benchmark targets:**
-- Typical config (1KB context, 5 artifact rules): **< 10ms** per read (imperceptible even 5x)
-- Large config (50KB context limit): **< 50ms** per read (acceptable for rare case)
-
-**If benchmarks fail:** Add simple caching:
-
-```typescript
-// Simple in-memory cache with no invalidation
-let cachedConfig: { mtime: number; config: ProjectConfig | null } | null = null;
-
-export function readProjectConfig(): ProjectConfig | null {
-  const projectRoot = findProjectRoot();
-  const configPath = path.join(projectRoot, 'openspec', 'config.yaml');
-
-  if (!existsSync(configPath)) {
-    return null;
-  }
-
-  const stats = statSync(configPath);
-  const mtime = stats.mtimeMs;
-
-  // Return cached config if file hasn't changed
-  if (cachedConfig && cachedConfig.mtime === mtime) {
-    return cachedConfig.config;
-  }
-
-  // Read and parse config
-  const config = parseConfigFile(configPath); // Extracted logic
-
-  // Cache result
-  cachedConfig = { mtime, config };
-  return config;
-}
-```
-
-**Performance testing task:** Add to Phase 6 (Testing)
-- Measure typical config read time (1KB context)
-- Measure large config read time (50KB context limit)
-- Measure repeated reads within single command
-- Document results, add caching only if needed
-
-## Data Flow
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│                                                              │
-│  User runs: openspec instructions proposal --change foo     │
-│                                                              │
-└────────────────────────────┬─────────────────────────────────┘
-                             │
-                             ▼
-┌──────────────────────────────────────────────────────────────┐
-│  resolveSchemaForChange("foo")                               │
-│                                                              │
-│  1. Check CLI flag ✗                                         │
-│  2. Check .openspec.yaml ✗                                   │
-│  3. Check openspec/config.yaml ✓ → "spec-driven"             │
-│                                                              │
-└────────────────────────────┬─────────────────────────────────┘
-                             │
-                             ▼
-┌──────────────────────────────────────────────────────────────┐
-│  loadInstructions("foo", "proposal")                         │
-│                                                              │
-│  1. Load spec-driven/artifacts/proposal.yaml                 │
-│  2. Read openspec/config.yaml                                │
-│  3. Build enriched instruction:                              │
-│     - <context>...</context>                                 │
-│     - <rules>...</rules>  (if rules.proposal exists)         │
-│     - <template>...</template>                               │
-│                                                              │
-└────────────────────────────┬─────────────────────────────────┘
-                             │
-                             ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Return InstructionOutput with enriched content              │
-│                                                              │
-│  Agent sees project context + rules + schema template        │
-│                                                              │
-└──────────────────────────────────────────────────────────────┘
-```
-
-## Risks / Trade-offs
-
-**[Risk]** Config typos silently ignored (e.g., wrong artifact ID in rules)
-→ **Mitigation:** Validate and warn on unknown artifact IDs during config load. Don't error to allow forward compatibility.
-
-**[Risk]** Context grows too large, pollutes all artifact instructions
-→ **Mitigation:** Document recommended size (< 500 chars). If this becomes an issue, add per-artifact context override later.
-
-**[Risk]** YAML parsing errors break OpenSpec commands
-→ **Mitigation:** Catch parse errors, log warning, fall back to defaults. Commands remain functional.
-
-**[Risk]** Config cached incorrectly across commands
-→ **Mitigation:** Read config fresh on each `readProjectConfig()` call. No caching layer for v1 (simplicity over perf).
-
-**[Trade-off]** Context is injected into ALL artifacts
-→ **Benefit:** Consistent project knowledge across workflow
-→ **Cost:** Can't scope context to specific artifacts (yet)
-→ **Future:** Add `context: { global: "...", proposal: "..." }` if needed
-
-**[Trade-off]** Rules use artifact IDs, not human names
-→ **Benefit:** Stable identifiers (IDs don't change)
-→ **Cost:** User needs to know artifact IDs from schema
-→ **Mitigation:** Document common artifact IDs, show in `openspec status` output
-
-## Migration Plan
-
-**No migration needed** - this is a new feature with no existing state.
-
-**Rollout steps:**
-1. Deploy with config loading behind feature flag (optional, for safety)
-2. Test with internal project (this repo)
-3. Document in README with examples
-4. Remove feature flag if used
-
-**Rollback strategy:**
-- Config is additive only (doesn't break existing changes)
-- If bugs found, config parsing can be disabled with env var
-- Users can delete config file to restore old behavior
-
-## Open Questions
-
-**Q: Should context support file references (`context: ./CONTEXT.md`)?**
-**A (deferred):** Start with string-only. Add file reference later if users request it. Keeps v1 simple.
-
-**Q: Should we support `.yml` alias in addition to `.yaml`?**
-**A:** Yes, check both extensions. Prefer `.yaml` in docs, but accept `.yml` for users who prefer it.
-
-**Q: What if config's schema field references a non-existent schema?**
-**A:** Schema resolution will fail downstream. Show error when trying to load schema, suggest valid schema names.
-
-**Q: Should rules be validated against the resolved schema's artifact IDs?**
-**A:** Yes, validate and warn, but don't halt. This allows forward compatibility if schema evolves.