sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/specs/config-loading/spec.md

@@ -1,122 +0,0 @@
-# config-loading Specification
-
-## Purpose
-Define how `openspec/config.yaml` is discovered, parsed, validated, and exposed to callers with safe fallbacks.
-
-## 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/specs/context-injection/spec.md

@@ -1,53 +0,0 @@
-# context-injection Specification
-
-## Purpose
-Define how project context from `openspec/config.yaml` is injected into workflow instructions while preserving source text and formatting.
-
-## 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/specs/docs-agent-instructions/spec.md

@@ -1,62 +0,0 @@
-# docs-agent-instructions Specification
-
-## Purpose
-Define authoring standards for generated agent instruction docs so templates, examples, and validation checklists are clear and copy-ready.
-
-## Requirements
-### Requirement: Quick Reference Placement
-The AI instructions SHALL begin with a quick-reference section that surfaces required file structures, templates, and formatting rules before any narrative guidance.
-
-#### Scenario: Loading templates at the top
-- **WHEN** `openspec/AGENTS.md` is regenerated or updated
-- **THEN** the first substantive section after the title SHALL provide copy-ready headings for `proposal.md`, `tasks.md`, spec deltas, and scenario formatting
-- **AND** link each template to the corresponding workflow step for deeper reading
-
-### Requirement: Embedded Templates and Examples
-`openspec/AGENTS.md` SHALL include complete copy/paste templates and inline examples exactly where agents make corresponding edits.
-
-#### Scenario: Providing file templates
-- **WHEN** authors reach the workflow guidance for drafting proposals and deltas
-- **THEN** provide fenced Markdown templates that match the required structure (`## Why`, `## ADDED Requirements`, `#### Scenario:` etc.)
-- **AND** accompany each template with a brief example showing correct header usage and scenario bullets
-
-### Requirement: Pre-validation Checklist
-`openspec/AGENTS.md` SHALL offer a concise pre-validation checklist that highlights common formatting mistakes before running `openspec validate`.
-
-#### Scenario: Highlighting common validation failures
-- **WHEN** a reader reaches the validation guidance
-- **THEN** present a checklist reminding them to verify requirement headers, scenario formatting, and delta sections
-- **AND** include reminders about at least `#### Scenario:` usage and descriptive requirement text before scenarios
-
-### Requirement: Progressive Disclosure of Workflow Guidance
-The documentation SHALL separate beginner essentials from advanced topics so newcomers can focus on core steps without losing access to advanced workflows.
-
-#### Scenario: Organizing beginner and advanced sections
-- **WHEN** reorganizing `openspec/AGENTS.md`
-- **THEN** keep an introductory section limited to the minimum steps (scaffold, draft, validate, request review)
-- **AND** move advanced topics (multi-capability changes, archiving details, tooling deep dives) into clearly labeled later sections
-- **AND** provide anchor links from the quick-reference to those advanced sections
-
-### Requirement: Behavior-First Spec Authoring Guidance
-Agent instruction docs SHALL explicitly teach that specs capture observable behavior contracts, while implementation details belong in design/tasks.
-
-#### Scenario: Distinguishing spec vs implementation content
-- **WHEN** `openspec/AGENTS.md` explains how to write `spec.md`
-- **THEN** it SHALL instruct agents to include externally verifiable behavior, inputs/outputs, errors, and constraints
-- **AND** it SHALL instruct agents to avoid internal library/framework choices and class/function-level implementation details in specs
-
-#### Scenario: Routing detail to the right artifact
-- **WHEN** implementation detail is necessary
-- **THEN** instructions SHALL direct the agent to place it in `design.md` or `tasks.md`, not in the behavioral requirements section of `spec.md`
-
-### Requirement: Lightweight-by-Default Guidance
-Agent instruction docs SHALL promote minimal ceremony and proportional rigor for spec authoring.
-
-#### Scenario: Applying progressive rigor
-- **WHEN** an agent drafts specs for routine changes
-- **THEN** instructions SHALL favor concise, lightweight requirements and scenarios
-- **AND** reserve deeper, fuller specification style for higher-risk changes (such as API breaks, migrations, cross-team, or security/privacy sensitive work)
-
-#### Scenario: Time-to-clarity optimization
-- **WHEN** guidance discusses drafting workflow
-- **THEN** it SHALL emphasize producing the smallest spec that is still testable and reviewable

package/OpenSpec-main/openspec/specs/global-config/spec.md

@@ -1,101 +0,0 @@
-# global-config Specification
-
-## Purpose
-
-This spec defines how OpenSpec resolves, reads, and writes user-level global configuration. It governs the `src/core/global-config.ts` module, which provides the foundation for storing user preferences, feature flags, and settings that persist across projects. The spec ensures cross-platform compatibility by following XDG Base Directory Specification with platform-specific fallbacks, and guarantees forward/backward compatibility through schema evolution rules.
-## Requirements
-### Requirement: Global configuration storage
-The system SHALL store global configuration in `~/.config/openspec/config.json`, including telemetry state with `anonymousId` and `noticeSeen` fields.
-
-#### Scenario: Initial config creation
-- **WHEN** no global config file exists
-- **AND** the first telemetry event is about to be sent
-- **THEN** the system creates `~/.config/openspec/config.json` with telemetry configuration
-
-#### Scenario: Telemetry config structure
-- **WHEN** reading or writing telemetry configuration
-- **THEN** the config contains a `telemetry` object with `anonymousId` (string UUID) and `noticeSeen` (boolean) fields
-
-#### Scenario: Config file format
-- **WHEN** storing configuration
-- **THEN** the system writes valid JSON that can be read and modified by users
-
-#### Scenario: Existing config preservation
-- **WHEN** adding telemetry fields to an existing config file
-- **THEN** the system preserves all existing configuration fields
-
-### Requirement: Global Config Directory Path
-
-The system SHALL resolve the global configuration directory path following XDG Base Directory Specification with platform-specific fallbacks.
-
-#### Scenario: Unix/macOS with XDG_CONFIG_HOME set
-- **WHEN** `$XDG_CONFIG_HOME` environment variable is set to `/custom/config`
-- **THEN** `getGlobalConfigDir()` returns `/custom/config/openspec`
-
-#### Scenario: Unix/macOS without XDG_CONFIG_HOME
-- **WHEN** `$XDG_CONFIG_HOME` environment variable is not set
-- **AND** the platform is Unix or macOS
-- **THEN** `getGlobalConfigDir()` returns `~/.config/openspec` (expanded to absolute path)
-
-#### Scenario: Windows platform
-- **WHEN** the platform is Windows
-- **AND** `%APPDATA%` is set to `C:\Users\User\AppData\Roaming`
-- **THEN** `getGlobalConfigDir()` returns `C:\Users\User\AppData\Roaming\openspec`
-
-### Requirement: Global Config Loading
-
-The system SHALL load global configuration from the config directory with sensible defaults when the config file does not exist or cannot be parsed.
-
-#### Scenario: Config file exists and is valid
-- **WHEN** `config.json` exists in the global config directory
-- **AND** the file contains valid JSON matching the config schema
-- **THEN** `getGlobalConfig()` returns the parsed configuration
-
-#### Scenario: Config file does not exist
-- **WHEN** `config.json` does not exist in the global config directory
-- **THEN** `getGlobalConfig()` returns the default configuration
-- **AND** no directory or file is created
-
-#### Scenario: Config file is invalid JSON
-- **WHEN** `config.json` exists but contains invalid JSON
-- **THEN** `getGlobalConfig()` returns the default configuration
-- **AND** a warning is logged to stderr
-
-### Requirement: Global Config Saving
-
-The system SHALL save global configuration to the config directory, creating the directory if it does not exist.
-
-#### Scenario: Save config to new directory
-- **WHEN** `saveGlobalConfig(config)` is called
-- **AND** the global config directory does not exist
-- **THEN** the directory is created
-- **AND** `config.json` is written with the provided configuration
-
-#### Scenario: Save config to existing directory
-- **WHEN** `saveGlobalConfig(config)` is called
-- **AND** the global config directory already exists
-- **THEN** `config.json` is written (overwriting if exists)
-
-### Requirement: Default Configuration
-
-The system SHALL provide a default configuration that is used when no config file exists.
-
-#### Scenario: Default config structure
-- **WHEN** no config file exists
-- **THEN** the default configuration includes an empty `featureFlags` object
-
-### Requirement: Config Schema Evolution
-
-The system SHALL merge loaded configuration with default values to ensure new config fields are available even when loading older config files.
-
-#### Scenario: Config file missing new fields
-- **WHEN** `config.json` exists with `{ "featureFlags": {} }`
-- **AND** the current schema includes a new field `defaultAiTool`
-- **THEN** `getGlobalConfig()` returns `{ featureFlags: {}, defaultAiTool: <default> }`
-- **AND** the loaded values take precedence over defaults for fields that exist in both
-
-#### Scenario: Config file has extra unknown fields
-- **WHEN** `config.json` contains fields not in the current schema
-- **THEN** the unknown fields are preserved in the returned configuration
-- **AND** no error or warning is raised
-

package/OpenSpec-main/openspec/specs/instruction-loader/spec.md

@@ -1,70 +0,0 @@
-# instruction-loader Specification
-
-## Purpose
-The instruction-loader loads instruction templates from schema directories, validates and enriches them with metadata and parameters (such as change context and dependency status), and exposes them for use by downstream services including template retrieval, parameter substitution, and enrichment.
-
-## Requirements
-### Requirement: Template Loading
-The system SHALL load templates from schema directories.
-
-#### Scenario: Load template from schema directory
-- **WHEN** `loadTemplate(schemaName, templatePath)` is called
-- **THEN** the system loads the template from `schemas/<schemaName>/templates/<templatePath>`
-
-#### Scenario: Template file 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 non-existent change directory
-- **WHEN** `loadChangeContext` is called for a non-existent change directory
-- **THEN** the system returns context with empty completed set
-
-### Requirement: Template Enrichment
-The system SHALL enrich templates with change-specific context.
-
-#### Scenario: Include artifact metadata
-- **WHEN** instructions are generated for an artifact
-- **THEN** the output includes change name, artifact ID, schema name, and output path
-
-#### Scenario: Include dependency status
-- **WHEN** an artifact has dependencies
-- **THEN** the output shows each dependency with completion status (done/missing)
-
-#### Scenario: Include unlocked artifacts
-- **WHEN** instructions are generated
-- **THEN** the output includes which artifacts become available after this one
-
-#### Scenario: Root artifact indicator
-- **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: All artifacts completed
-- **WHEN** all artifacts are completed
-- **THEN** status shows all artifacts as "done"
-
-#### Scenario: Mixed completion status
-- **WHEN** some artifacts are completed
-- **THEN** status shows completed as "done", ready as "ready", blocked as "blocked"
-
-#### Scenario: Blocked artifact details
-- **WHEN** an artifact is blocked
-- **THEN** status shows which dependencies are missing
-
-#### Scenario: Include output paths
-- **WHEN** status is formatted
-- **THEN** each artifact shows its output path pattern
-

package/OpenSpec-main/openspec/specs/legacy-cleanup/spec.md

@@ -1,163 +0,0 @@
-# legacy-cleanup Specification
-
-## Purpose
-Define detection and cleanup behavior for legacy OpenSpec artifacts during initialization and update workflows.
-
-## Requirements
-### Requirement: Legacy artifact detection
-
-The system SHALL detect legacy OpenSpec artifacts from previous init versions.
-
-#### Scenario: Detecting legacy config files
-
-- **WHEN** running `openspec init` on an existing project
-- **THEN** the system SHALL check for config files with OpenSpec markers:
-  - `CLAUDE.md`
-  - `.cursorrules`
-  - `.windsurfrules`
-  - `.clinerules`
-  - `.kilocode_rules`
-  - `.github/copilot-instructions.md`
-  - `.amazonq/instructions.md`
-  - `CODEBUDDY.md`
-  - `IFLOW.md`
-  - And all other tool config files from the legacy ToolRegistry
-
-#### Scenario: Detecting legacy slash command directories
-
-- **WHEN** running `openspec init` on an existing project
-- **THEN** the system SHALL check for old slash command directories:
-  - `.claude/commands/openspec/`
-  - `.cursor/commands/openspec/` (note: old format used `openspec-*.md` in commands root)
-  - `.windsurf/workflows/openspec-*.md`
-  - And equivalent directories for all tools in the legacy SlashCommandRegistry
-
-#### Scenario: Detecting legacy OpenSpec structure files
-
-- **WHEN** running `openspec init` on an existing project
-- **THEN** the system SHALL check for:
-  - `openspec/AGENTS.md`
-  - `openspec/project.md` (for migration messaging only, not deleted)
-  - Root `AGENTS.md` with OpenSpec markers
-
-### Requirement: Legacy cleanup confirmation
-
-The system SHALL prompt for confirmation before removing legacy artifacts.
-
-#### Scenario: Prompting for cleanup when legacy detected
-
-- **WHEN** legacy artifacts are detected
-- **THEN** the system SHALL display what was found
-- **AND** prompt: "Legacy files detected. Upgrade and clean up? [Y/n]"
-- **AND** default to Yes if user presses Enter
-
-#### Scenario: User confirms cleanup
-
-- **WHEN** user responds Y or presses Enter
-- **THEN** the system SHALL remove legacy artifacts
-- **AND** proceed with skill-based setup
-
-#### Scenario: User declines cleanup
-
-- **WHEN** user responds N
-- **THEN** the system SHALL abort initialization
-- **AND** display message suggesting manual cleanup or using `--force` flag
-
-#### Scenario: Non-interactive mode
-
-- **WHEN** running with `--no-interactive` or in CI environment
-- **AND** legacy artifacts are detected
-- **THEN** the system SHALL abort with exit code 1
-- **AND** display detected legacy artifacts
-- **AND** suggest running interactively or using `--force` flag
-
-### Requirement: Surgical removal of config file content
-
-The system SHALL preserve user content when removing OpenSpec markers from config files.
-
-#### Scenario: Config file with only OpenSpec content
-
-- **WHEN** a config file contains only OpenSpec marker block (whitespace outside is acceptable)
-- **THEN** the system SHALL remove the OpenSpec marker block
-- **AND** preserve the file (even if empty or whitespace-only)
-- **AND** NOT delete the file (config files belong to the user's project root)
-
-#### Scenario: Config file with mixed content
-
-- **WHEN** a config file contains content outside OpenSpec markers
-- **THEN** the system SHALL remove only the `<!-- OPENSPEC:START -->` to `<!-- OPENSPEC:END -->` block
-- **AND** preserve all content before and after the markers
-- **AND** clean up any resulting double blank lines
-
-#### Scenario: Root AGENTS.md with mixed content
-
-- **WHEN** root `AGENTS.md` contains OpenSpec markers AND other content
-- **THEN** the system SHALL remove only the OpenSpec marker block
-- **AND** preserve the rest of the file
-
-### Requirement: Legacy directory removal
-
-The system SHALL remove legacy slash command directories entirely.
-
-#### Scenario: Removing old slash command directory
-
-- **WHEN** a legacy slash command directory exists (e.g., `.claude/commands/openspec/`)
-- **THEN** the system SHALL delete the entire directory and its contents
-- **AND** NOT delete the parent directory (e.g., `.claude/commands/` remains)
-
-#### Scenario: Removing legacy AGENTS.md
-
-- **WHEN** `openspec/AGENTS.md` exists
-- **THEN** the system SHALL delete the file
-- **AND** NOT delete the `openspec/` directory itself
-
-### Requirement: project.md migration hint
-
-The system SHALL preserve project.md and display a migration hint instead of deleting it.
-
-#### Scenario: project.md exists during upgrade
-
-- **WHEN** `openspec/project.md` exists during legacy cleanup
-- **THEN** the system SHALL NOT delete the file
-- **AND** the system SHALL display a migration hint in the output:
-  ```
-  Manual migration needed:
-    → openspec/project.md still exists
-      Move useful content to config.yaml's "context:" field, then delete
-  ```
-
-#### Scenario: project.md migration rationale
-
-- **GIVEN** project.md may contain user-written project documentation
-- **AND** config.yaml's context field serves the same purpose (auto-injected into artifacts)
-- **WHEN** displaying the migration hint
-- **THEN** users can migrate manually or use `/opsx:explore` to get AI assistance
-
-### Requirement: Cleanup reporting
-
-The system SHALL report what was cleaned up.
-
-#### Scenario: Displaying cleanup summary
-
-- **WHEN** legacy cleanup completes
-- **THEN** the system SHALL display a summary section:
-  ```
-  Cleaned up legacy files:
-    ✓ Removed OpenSpec markers from CLAUDE.md
-    ✓ Removed .claude/commands/openspec/ (replaced by /opsx:*)
-    ✓ Removed openspec/AGENTS.md (no longer needed)
-  ```
-- **AND IF** `openspec/project.md` exists
-- **THEN** the system SHALL display a separate migration section:
-  ```
-  Manual migration needed:
-    → openspec/project.md still exists
-      Move useful content to config.yaml's "context:" field, then delete
-  ```
-
-#### Scenario: No legacy detected
-
-- **WHEN** no legacy artifacts are found
-- **THEN** the system SHALL NOT display the cleanup section
-- **AND** proceed directly with skill setup
-