sauron-cli 1.1.3 → 1.3.0

package/OpenSpec-main/openspec/changes/archive/2026-02-17-project-config/specs/config-loading/spec.md

@@ -0,0 +1,119 @@
+# Spec: Config Loading
+
+## ADDED Requirements
+
+### Requirement: Load project config from openspec/config.yaml
+
+The system SHALL read and parse the project configuration file located at `openspec/config.yaml` relative to the project root.
+
+#### Scenario: Valid config file exists
+- **WHEN** `openspec/config.yaml` exists with valid YAML content
+- **THEN** system parses the file and returns a ProjectConfig object
+
+#### Scenario: Config file does not exist
+- **WHEN** `openspec/config.yaml` does not exist
+- **THEN** system returns null without error
+
+#### Scenario: Config file has invalid YAML syntax
+- **WHEN** `openspec/config.yaml` contains malformed YAML
+- **THEN** system logs a warning message and returns null
+
+#### Scenario: Config file has valid YAML but invalid schema
+- **WHEN** `openspec/config.yaml` contains valid YAML that fails Zod schema validation
+- **THEN** system logs a warning message with validation details and returns null
+
+### Requirement: Support .yml file extension alias
+
+The system SHALL accept both `.yaml` and `.yml` file extensions for the config file.
+
+#### Scenario: Config file uses .yml extension
+- **WHEN** `openspec/config.yml` exists and `openspec/config.yaml` does not exist
+- **THEN** system reads from `openspec/config.yml`
+
+#### Scenario: Both .yaml and .yml exist
+- **WHEN** both `openspec/config.yaml` and `openspec/config.yml` exist
+- **THEN** system prefers `openspec/config.yaml`
+
+### Requirement: Use resilient field-by-field parsing
+
+The system SHALL parse each config field independently, collecting valid fields and warning about invalid ones without rejecting the entire config.
+
+#### Scenario: Schema field is valid
+- **WHEN** config contains `schema: "spec-driven"`
+- **THEN** schema field is included in returned config
+
+#### Scenario: Schema field is missing
+- **WHEN** config lacks the `schema` field
+- **THEN** no warning is logged (field is optional at parse level)
+
+#### Scenario: Schema field is empty string
+- **WHEN** config contains `schema: ""`
+- **THEN** warning is logged and schema field is not included in returned config
+
+#### Scenario: Schema field is invalid type
+- **WHEN** config contains `schema: 123` (number instead of string)
+- **THEN** warning is logged and schema field is not included in returned config
+
+#### Scenario: Context field is valid
+- **WHEN** config contains `context: "Tech stack: TypeScript"`
+- **THEN** context field is included in returned config
+
+#### Scenario: Context field is invalid type
+- **WHEN** config contains `context: 123` (number instead of string)
+- **THEN** warning is logged and context field is not included in returned config
+
+#### Scenario: Rules field has valid structure
+- **WHEN** config contains `rules: { proposal: ["Rule 1"], specs: ["Rule 2"] }`
+- **THEN** rules field is included in returned config with valid rules
+
+#### Scenario: Rules field has non-array value for artifact
+- **WHEN** config contains `rules: { proposal: "not an array", specs: ["Valid"] }`
+- **THEN** warning is logged for proposal, but specs rules are still included in returned config
+
+#### Scenario: Rules array contains non-string elements
+- **WHEN** config contains `rules: { proposal: ["Valid rule", 123, ""] }`
+- **THEN** only "Valid rule" is included, warning logged about invalid elements
+
+#### Scenario: Mix of valid and invalid fields
+- **WHEN** config contains valid schema, invalid context type, valid rules
+- **THEN** config is returned with schema and rules fields, warning logged about context
+
+### Requirement: Enforce context size limit
+
+The system SHALL reject context fields exceeding 50KB and log a warning.
+
+#### Scenario: Context within size limit
+- **WHEN** config contains context of 1KB
+- **THEN** context is included in returned config
+
+#### Scenario: Context at size limit
+- **WHEN** config contains context of exactly 50KB
+- **THEN** context is included in returned config
+
+#### Scenario: Context exceeds size limit
+- **WHEN** config contains context of 51KB
+- **THEN** warning is logged with size and limit, context field is not included in returned config
+
+### Requirement: Defer artifact ID validation to instruction loading
+
+The system SHALL NOT validate artifact IDs in rules during config load time. Validation happens during instruction loading when schema is known.
+
+#### Scenario: Config with rules is loaded
+- **WHEN** config contains `rules: { unknownartifact: [...] }`
+- **THEN** config is loaded successfully without validation errors
+
+#### Scenario: Validation happens at instruction load time
+- **WHEN** instructions are loaded for any artifact and config has unknown artifact IDs in rules
+- **THEN** warnings are emitted about unknown artifact IDs (see rules-injection spec for details)
+
+### Requirement: Gracefully handle config errors without halting
+
+The system SHALL continue operation with default values when config loading or parsing fails.
+
+#### Scenario: Config parse failure during command execution
+- **WHEN** config file has syntax errors and user runs `openspec new change`
+- **THEN** command executes using default schema "spec-driven"
+
+#### Scenario: Warning is visible to user
+- **WHEN** config loading fails
+- **THEN** system outputs warning message to stderr with details about the failure

package/OpenSpec-main/openspec/changes/archive/2026-02-17-project-config/specs/context-injection/spec.md

@@ -0,0 +1,51 @@
+# Spec: Context Injection
+
+## ADDED Requirements
+
+### Requirement: Inject context into all artifact instructions
+
+The system SHALL inject the context field from project config into instructions for all artifacts, wrapped in XML-style `<context>` tags.
+
+#### Scenario: Config has context field
+- **WHEN** config contains `context: "Tech stack: TypeScript, React"`
+- **THEN** instruction output includes `<context>\nTech stack: TypeScript, React\n</context>`
+
+#### Scenario: Config has no context field
+- **WHEN** config omits the context field or context is undefined
+- **THEN** instruction output does not include `<context>` tags
+
+#### Scenario: Context is multi-line string
+- **WHEN** config contains context with multiple lines
+- **THEN** instruction output preserves line breaks within `<context>` tags
+
+#### Scenario: Context applied to all artifacts
+- **WHEN** instructions are loaded for any artifact (proposal, specs, design, tasks)
+- **THEN** context section appears in all instruction outputs
+
+### Requirement: Format context with XML-style tags
+
+The system SHALL wrap context content in `<context>` opening and `</context>` closing tags with content on separate lines.
+
+#### Scenario: Context tag structure
+- **WHEN** context is injected into instructions
+- **THEN** format is exactly `<context>\n{content}\n</context>\n\n`
+
+#### Scenario: Context appears before template
+- **WHEN** instructions are generated with context
+- **THEN** `<context>` section appears before the `<template>` section
+
+### Requirement: Preserve context content exactly as provided
+
+The system SHALL inject context content without modification, escaping, or interpretation.
+
+#### Scenario: Context contains special characters
+- **WHEN** context includes characters like `<`, `>`, `&`, quotes
+- **THEN** characters are preserved exactly as written in the config
+
+#### Scenario: Context contains URLs
+- **WHEN** context includes URLs like "docs at https://example.com"
+- **THEN** URLs are preserved exactly in the injected content
+
+#### Scenario: Context contains markdown
+- **WHEN** context includes markdown formatting like `**bold**` or `[links](url)`
+- **THEN** markdown is preserved without rendering or escaping

package/OpenSpec-main/openspec/changes/archive/2026-02-17-project-config/specs/rules-injection/spec.md

@@ -0,0 +1,99 @@
+# Spec: Rules Injection
+
+## ADDED Requirements
+
+### Requirement: Inject rules only for matching artifact
+
+The system SHALL inject rules from config into instructions only when the artifact ID matches a key in the rules object.
+
+#### Scenario: Rules exist for the artifact
+- **WHEN** loading instructions for "proposal" and config has `rules: { proposal: ["Rule 1", "Rule 2"] }`
+- **THEN** instruction output includes rules section with both rules
+
+#### Scenario: No rules for the artifact
+- **WHEN** loading instructions for "design" and config has `rules: { proposal: [...] }`
+- **THEN** instruction output does not include `<rules>` tags
+
+#### Scenario: Rules object is undefined
+- **WHEN** config omits the rules field or rules is undefined
+- **THEN** instruction output does not include `<rules>` tags for any artifact
+
+#### Scenario: Rules array is empty for artifact
+- **WHEN** config has `rules: { proposal: [] }`
+- **THEN** instruction output does not include `<rules>` tags
+
+### Requirement: Format rules with XML-style tags and bullet list
+
+The system SHALL wrap rules in `<rules>` tags with each rule as a bulleted list item.
+
+#### Scenario: Single rule for artifact
+- **WHEN** config has `rules: { proposal: ["Include rollback plan"] }`
+- **THEN** instruction output includes `<rules>\n- Include rollback plan\n</rules>\n\n`
+
+#### Scenario: Multiple rules for artifact
+- **WHEN** config has `rules: { proposal: ["Rule 1", "Rule 2", "Rule 3"] }`
+- **THEN** instruction output includes each rule as separate bullet point
+
+#### Scenario: Rules appear after context and before template
+- **WHEN** instructions are generated with both context and rules
+- **THEN** order is `<context>` then `<rules>` then `<template>`
+
+### Requirement: Preserve rule text exactly as provided
+
+The system SHALL inject rule text without modification, escaping, or interpretation.
+
+#### Scenario: Rule contains markdown
+- **WHEN** rule includes markdown like "Use **Given/When/Then** format"
+- **THEN** markdown is preserved in the injected content
+
+#### Scenario: Rule contains special characters
+- **WHEN** rule includes characters like `<`, `>`, quotes
+- **THEN** characters are preserved exactly as written
+
+#### Scenario: Rule is multi-line string
+- **WHEN** rule text contains line breaks
+- **THEN** line breaks are preserved within the bullet point
+
+### Requirement: Support multiple artifacts with different rules
+
+The system SHALL allow different rule sets for different artifacts in the same config.
+
+#### Scenario: Multiple artifacts have rules
+- **WHEN** config has `rules: { proposal: ["P1"], specs: ["S1", "S2"], tasks: ["T1"] }`
+- **THEN** proposal instructions show only ["P1"], specs show only ["S1", "S2"], tasks show only ["T1"]
+
+#### Scenario: Some artifacts have rules, others do not
+- **WHEN** config has rules for proposal and specs only
+- **THEN** design and tasks instructions have no `<rules>` section
+
+### Requirement: Rules are additive to schema guidance
+
+The system SHALL add config rules to the schema's built-in artifact instruction, not replace it.
+
+#### Scenario: Artifact has schema instruction and config rules
+- **WHEN** artifact has built-in instruction from schema and config provides rules
+- **THEN** final instruction contains both schema guidance and config rules
+
+#### Scenario: Rules provide additional constraints
+- **WHEN** schema says "create proposal" and config rules say "include rollback plan"
+- **THEN** agent sees both the schema template and the additional rule
+
+### Requirement: Validate artifact IDs during instruction loading
+
+The system SHALL validate artifact IDs in rules against the schema when instructions are loaded and emit warnings for unknown IDs.
+
+#### Scenario: All artifact IDs are valid
+- **WHEN** instructions loaded and config has `rules: { proposal: [...], specs: [...] }` for schema with those artifacts
+- **THEN** no validation warnings are emitted
+
+#### Scenario: Unknown artifact ID in rules
+- **WHEN** instructions loaded and config has `rules: { unknownartifact: [...] }`
+- **THEN** warning emitted: "Unknown artifact ID in rules: 'unknownartifact'. Valid IDs for schema 'spec-driven': design, proposal, specs, tasks"
+
+#### Scenario: Multiple unknown artifact IDs
+- **WHEN** instructions loaded and config has multiple unknown artifact IDs
+- **THEN** separate warning emitted for each unknown artifact ID
+
+#### Scenario: Validation warnings shown once per session
+- **WHEN** instructions loaded multiple times in same CLI session
+- **THEN** each unique validation warning is shown only once (cached)

package/OpenSpec-main/openspec/changes/archive/2026-02-17-project-config/specs/schema-resolution/spec.md

@@ -0,0 +1,83 @@
+# Spec: Schema Resolution with Config
+
+## ADDED Requirements
+
+### Requirement: Use config schema as default for new changes
+
+The system SHALL use the schema field from `openspec/config.yaml` as the default when creating new changes without explicit `--schema` flag.
+
+#### Scenario: Create change without --schema flag and config exists
+- **WHEN** user runs `openspec new change foo` and config contains `schema: "tdd"`
+- **THEN** system creates change with schema "tdd"
+
+#### Scenario: Create change without --schema flag and no config
+- **WHEN** user runs `openspec new change foo` and no config file exists
+- **THEN** system creates change with default schema "spec-driven"
+
+#### Scenario: Create change with explicit --schema flag
+- **WHEN** user runs `openspec new change foo --schema custom` and config contains `schema: "tdd"`
+- **THEN** system creates change with schema "custom" (CLI flag overrides config)
+
+### Requirement: Resolve schema with updated precedence order
+
+The system SHALL resolve the schema for a change using the following precedence order: CLI flag, change metadata, project config, hardcoded default.
+
+#### Scenario: CLI flag is provided
+- **WHEN** user runs command with `--schema custom`
+- **THEN** system uses "custom" regardless of change metadata or config
+
+#### Scenario: Change metadata specifies schema
+- **WHEN** change has `.openspec.yaml` with `schema: bound` and config has `schema: tdd`
+- **THEN** system uses "bound" from change metadata
+
+#### Scenario: Only project config specifies schema
+- **WHEN** no CLI flag or change metadata, but config has `schema: tdd`
+- **THEN** system uses "tdd" from project config
+
+#### Scenario: No schema specified anywhere
+- **WHEN** no CLI flag, change metadata, or project config
+- **THEN** system uses hardcoded default "spec-driven"
+
+### Requirement: Support project-local schema names in config
+
+The system SHALL allow the config schema field to reference project-local schemas defined in `openspec/schemas/`.
+
+#### Scenario: Config references project-local schema
+- **WHEN** config contains `schema: "my-workflow"` and `openspec/schemas/my-workflow/` exists
+- **THEN** system resolves to the project-local schema
+
+#### Scenario: Config references non-existent schema
+- **WHEN** config contains `schema: "nonexistent"` and that schema does not exist
+- **THEN** system shows error when attempting to load the schema with fuzzy match suggestions and list of all valid schemas
+
+### Requirement: Provide helpful error message for invalid schema
+
+The system SHALL display schema error with fuzzy match suggestions, list of available schemas, and fix instructions.
+
+#### Scenario: Schema name with typo (close match)
+- **WHEN** config contains `schema: "spce-driven"` (typo)
+- **THEN** error message includes "Did you mean: spec-driven (built-in)" as suggestion
+
+#### Scenario: Schema name with no close matches
+- **WHEN** config contains `schema: "completely-wrong"`
+- **THEN** error message shows list of all available built-in and project-local schemas
+
+#### Scenario: Error message includes fix instructions
+- **WHEN** config references invalid schema
+- **THEN** error message includes "Fix: Edit openspec/config.yaml and change 'schema: X' to a valid schema name"
+
+#### Scenario: Error distinguishes built-in vs project-local schemas
+- **WHEN** error lists available schemas
+- **THEN** output clearly labels each as "built-in" or "project-local"
+
+### Requirement: Maintain backwards compatibility for existing changes
+
+The system SHALL continue to work with existing changes that do not have project config.
+
+#### Scenario: Existing change without config
+- **WHEN** change was created before config feature and no config file exists
+- **THEN** system resolves schema using existing logic (change metadata or hardcoded default)
+
+#### Scenario: Existing change with config added later
+- **WHEN** config file is added to project with existing changes
+- **THEN** existing changes continue to use their bound schema from `.openspec.yaml`

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

@@ -0,0 +1,72 @@
+## 1. Core Config System
+
+- [x] 1.1 Create `src/core/project-config.ts` with ProjectConfigSchema using Zod (for docs and type inference)
+- [x] 1.2 Implement `readProjectConfig()` with resilient field-by-field parsing using Zod's `safeParse()`
+- [x] 1.3 Add support for both .yaml and .yml extensions (prefer .yaml)
+- [x] 1.4 Add 50KB hard limit for context field with size check and warning
+- [x] 1.5 Implement `validateConfigRules()` to validate artifact IDs against schema (called during instruction loading)
+- [x] 1.6 Implement `suggestSchemas()` with Levenshtein distance fuzzy matching for helpful error messages
+- [x] 1.7 Add unit tests for resilient parsing (partial configs, field-level errors with Zod safeParse)
+- [x] 1.8 Add unit tests for context size limit enforcement
+- [x] 1.9 Add unit tests for .yml/.yaml precedence
+- [x] 1.10 Add unit tests for fuzzy schema matching with typos
+
+## 2. Schema Resolution Integration
+
+- [x] 2.1 Update `resolveSchemaForChange()` in `src/utils/change-metadata.ts` to check project config (3rd in precedence)
+- [x] 2.2 Update `createNewChange()` in `src/utils/change-utils.ts` to use config schema as default
+- [x] 2.3 Add integration tests for schema resolution precedence (CLI → change metadata → config → default)
+- [x] 2.4 Add test for project-local schema names in config
+- [x] 2.5 Add test for non-existent schema error handling with suggestions
+
+## 3. Context and Rules Injection
+
+- [x] 3.1 Update `loadInstructions()` in `src/core/artifact-graph/instruction-loader.ts` to inject context for all artifacts
+- [x] 3.2 Add rules injection logic for matching artifacts only with XML tags and bullet formatting
+- [x] 3.3 Add validation call during instruction loading to check artifact IDs in rules
+- [x] 3.4 Implement session-level warning cache to avoid repeating same validation warnings
+- [x] 3.5 Implement proper ordering: `<context>` → `<rules>` → `<template>`
+- [x] 3.6 Preserve multi-line strings and special characters without escaping
+- [x] 3.7 Add unit tests for context injection (present, absent, multi-line, special chars)
+- [x] 3.8 Add unit tests for rules injection (matching artifact, non-matching, empty array, multiple artifacts)
+- [x] 3.9 Add unit tests for validation timing (warnings during instruction load, not config load)
+- [x] 3.10 Add unit tests for warning deduplication (same warning shown once per session)
+- [x] 3.11 Add integration test verifying full instruction output with context + rules + template
+
+## 4. Interactive Config Creation
+
+- [x] 4.1 Add @inquirer/prompts dependency to package.json
+- [x] 4.2 Create `src/core/config-prompts.ts` with ConfigPromptResult interface
+- [x] 4.3 Implement `promptForConfig()` function with schema selection prompt
+- [x] 4.4 Add multi-line context input prompt with examples and skip option
+- [x] 4.5 Add per-artifact rules prompts with checkbox selection and line-by-line input
+- [x] 4.6 Implement YAML serialization with proper multi-line string formatting
+- [x] 4.7 Add validation and retry logic for prompt errors
+
+## 5. Experimental Setup Integration
+
+- [x] 5.1 Update `artifactExperimentalSetupCommand()` in `src/commands/artifact-workflow.ts` to check for existing config
+- [x] 5.2 Add config creation section after skills/commands creation with header and description
+- [x] 5.3 Integrate `promptForConfig()` calls with proper flow control
+- [x] 5.4 Add Ctrl+C (ExitPromptError) handling - log cancellation message, continue with setup (non-fatal)
+- [x] 5.5 Write created config to `openspec/config.yaml` using YAML stringify
+- [x] 5.6 Display success summary showing path, schema, context lines, rules count
+- [x] 5.7 Show usage examples and git commit suggestion
+- [x] 5.8 Handle existing config case with skip message and manual update instructions
+- [x] 5.9 Add error handling for file write failures with fallback suggestions
+- [x] 5.10 Add test for cancellation behavior (skills/commands preserved, config not created)
+
+## 6. Testing and Documentation
+
+- [x] 6.1 Add end-to-end test: run experimental setup → create config → create change → verify schema used
+- [x] 6.2 Add end-to-end test: create config → get instructions → verify context and rules injected
+- [x] 6.3 Test backwards compatibility: existing changes work without config
+- [x] 6.4 Test config changes are reflected immediately (no stale cache)
+- [x] 6.5 Add performance benchmark: measure config read time with typical config (1KB context)
+- [x] 6.6 Add performance benchmark: measure config read time with large config (50KB context)
+- [x] 6.7 Add performance benchmark: measure repeated reads within single command
+- [x] 6.8 Document benchmark results and decide if caching is needed (target: <10ms typical, <50ms acceptable)
+- [x] 6.9 If benchmarks fail: implement mtime-based caching with cache invalidation
+- [x] 6.10 Update README or docs with config feature examples and schema
+- [x] 6.11 Document common artifact IDs for different schemas
+- [x] 6.12 Add troubleshooting section for config validation errors

package/OpenSpec-main/openspec/changes/archive/2026-02-17-project-local-schemas/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: "2025-01-13"

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

@@ -0,0 +1,117 @@
+## Context
+
+OpenSpec currently resolves schemas from two locations:
+1. User override: `~/.local/share/openspec/schemas/<name>/`
+2. Package built-in: `<npm-package>/schemas/<name>/`
+
+This change adds a third, highest-priority level: project-local schemas at `./openspec/schemas/<name>/`.
+
+The resolver functions in `src/core/artifact-graph/resolver.ts` currently don't take a `projectRoot` parameter because user and package paths are absolute. To support project-local schemas, we need to pass project root context into the resolver.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Enable version-controlled custom workflow schemas
+- Allow teams to share schemas via git without per-machine setup
+- Maintain backward compatibility with existing resolver API
+- Integrate with `config.yaml`'s `schema` field (from project-config change)
+
+**Non-Goals:**
+- Schema inheritance or `extends` keyword
+- Template-level overrides (partial forks)
+- Schema management CLI commands (`openspec schema copy/which/diff/reset`)
+- Validation that project-local schema names don't conflict with built-ins (shadowing is intentional)
+
+## Decisions
+
+### Decision 1: Add optional `projectRoot` parameter to resolver functions
+
+**Choice:** Add optional `projectRoot?: string` parameter to resolver functions rather than using `process.cwd()` internally.
+
+**Alternatives considered:**
+- Use `process.cwd()` internally: Simpler API but implicit, harder to test, doesn't match existing codebase patterns
+- Create separate project-aware functions: No breaking changes but awkward API, callers must compose
+
+**Rationale:** The codebase already follows a pattern where CLI commands get project root via `process.cwd()` and pass it down to functions that need it. Adding an optional parameter maintains backward compatibility while enabling explicit, testable behavior.
+
+**Affected functions:**
+```typescript
+getSchemaDir(name: string, projectRoot?: string): string | null
+listSchemas(projectRoot?: string): string[]
+listSchemasWithInfo(projectRoot?: string): SchemaInfo[]
+resolveSchema(name: string, projectRoot?: string): SchemaYaml
+```
+
+### Decision 2: Resolution order is project → user → package
+
+**Choice:** Project-local schemas have highest priority, then user overrides, then package built-ins.
+
+**Rationale:**
+- Project-local should win because it represents team intent (version controlled, shared)
+- User overrides still useful for personal experimentation without affecting team
+- Package built-ins are the fallback defaults
+
+```
+1. ./openspec/schemas/<name>/              # Project-local (highest)
+2. ~/.local/share/openspec/schemas/<name>/ # User override
+3. <npm-package>/schemas/<name>/           # Package built-in (lowest)
+```
+
+### Decision 3: Add `getProjectSchemasDir()` helper function
+
+**Choice:** Create a dedicated function to get the project schemas directory path.
+
+```typescript
+function getProjectSchemasDir(projectRoot: string): string {
+  return path.join(projectRoot, 'openspec', 'schemas');
+}
+```
+
+**Rationale:** Matches existing pattern with `getPackageSchemasDir()` and `getUserSchemasDir()`. Keeps path logic centralized.
+
+### Decision 4: Extend `SchemaInfo.source` to include `'project'`
+
+**Choice:** Update the source type from `'package' | 'user'` to `'project' | 'user' | 'package'`.
+
+**Rationale:** Consumers need to distinguish project-local schemas for display purposes (e.g., `schemasCommand` output).
+
+### Decision 5: No special handling for schema name conflicts
+
+**Choice:** If a project-local schema has the same name as a built-in (e.g., `spec-driven`), the project-local version wins. No warning, no error.
+
+**Rationale:** This is intentional shadowing. Teams may want to customize a built-in schema while keeping the same name for familiarity.
+
+## Risks / Trade-offs
+
+### Risk: Confusion when project schema shadows built-in
+A team could create `openspec/schemas/spec-driven/` that shadows the built-in, causing confusion when someone expects default behavior.
+
+**Mitigation:** The `openspec schemas` command shows the source of each schema. Users can see `spec-driven (project)` vs `spec-driven (package)`.
+
+### Risk: Missing projectRoot parameter
+If callers forget to pass `projectRoot`, project-local schemas won't be found.
+
+**Mitigation:**
+- Make the change incrementally, updating call sites that need project-local support
+- Existing behavior (user + package only) is preserved when `projectRoot` is undefined
+
+### Trade-off: Optional parameter vs required
+Making `projectRoot` optional maintains backward compatibility but means some code paths may silently skip project-local resolution.
+
+**Accepted:** Backward compatibility is more important. The main entry points (CLI commands) will always pass `projectRoot`.
+
+## Implementation Approach
+
+1. **Update `resolver.ts`:**
+   - Add `getProjectSchemasDir(projectRoot: string)` function
+   - Update `getSchemaDir()` to check project-local first when `projectRoot` provided
+   - Update `listSchemas()` to include project schemas when `projectRoot` provided
+   - Update `listSchemasWithInfo()` to return `source: 'project'` for project schemas
+   - Update `SchemaInfo` type to include `'project'` in source union
+
+2. **Update `artifact-workflow.ts`:**
+   - Update `schemasCommand` to pass `projectRoot` and display source labels
+
+3. **Update call sites:**
+   - Any existing code that needs project-local resolution should pass `projectRoot`
+   - `config.yaml` schema resolution already has access to `projectRoot`