sauron-cli 1.3.0 → 1.4.0

package/OpenSpec-main/openspec/changes/archive/2026-01-06-add-specs-apply-command/tasks.md

@@ -1,40 +0,0 @@
-## Tasks
-
-### Core Implementation
-
-- [x] Extract spec application logic from `ArchiveCommand` into `src/core/specs-apply.ts`
-  - Move `buildUpdatedSpec()`, `findSpecUpdates()`, `writeUpdatedSpec()` to shared module
-  - Keep `ArchiveCommand` importing from the new module
-  - Ensure all validation logic is preserved
-
-### Skill Template
-
-- [x] Add `getSyncSpecsSkillTemplate()` function in `src/core/templates/skill-templates.ts`
-  - Skill name: `openspec-sync-specs`
-  - Description: Sync delta specs to main specs
-  - **Agent-driven**: Instructions for agent to read deltas and edit main specs directly
-
-- [x] Add `/opsx:sync` slash command template in `skill-templates.ts`
-  - Mirror the skill template for slash command format
-  - **Agent-driven**: No CLI command, agent does the merge
-
-### Registration
-
-- [x] Register skill in managed skills (via `artifact-experimental-setup`)
-  - Add to skill list with appropriate metadata
-  - Ensure it appears in setup output
-
-### Design Decision
-
-**Why agent-driven instead of CLI-driven?**
-
-The programmatic merge operates at requirement-level granularity:
-- MODIFIED requires copying ALL scenarios, not just the changed ones
-- If agent forgets a scenario, it gets deleted
-- Delta specs become bloated with copied content
-
-Agent-driven approach:
-- Agent can apply partial updates (add a scenario without copying others)
-- Delta represents *intent*, not wholesale replacement
-- More flexible and natural editing workflow
-- Archive still uses programmatic merge (for finalized changes)

package/OpenSpec-main/openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/proposal.md

@@ -1,138 +0,0 @@
-## Why
-
-The `generateApplyInstructions` function is hardcoded to check for `spec-driven` artifacts (`proposal.md`, `specs/`, `design.md`, `tasks.md`). If a user selects a different schema like `tdd`, the apply instructions are meaningless - they check for files that don't exist in that schema.
-
-This blocks the experimental workflow from supporting multiple schemas properly.
-
-## What Changes
-
-**Scope: Experimental artifact workflow** (`openspec instructions apply`)
-
-**Depends on:** `add-per-change-schema-metadata` (to know which schema a change uses)
-
-- Make `generateApplyInstructions` read artifact definitions from the schema
-- Dynamically determine which artifacts exist based on schema
-- Define when a change becomes "implementable" (see Design Decision below)
-- Generate schema-appropriate context files and instructions
-
-## Design Decision: When is a change implementable?
-
-This is the key question. Different approaches:
-
-### Option A: Explicit `apply` artifact in schema
-
-Add a field to mark which artifact is the "implementation gate":
-
-```yaml
-artifacts:
-  - id: tasks
-    generates: tasks.md
-    apply: true  # ← This artifact triggers apply mode
-```
-
-**Pros:** Explicit, flexible
-**Cons:** Another field to maintain, what if multiple artifacts are `apply: true`?
-
-### Option B: Leaf artifacts are implementable
-
-The artifact(s) with no dependents (nothing depends on them) are the apply target.
-
-- `spec-driven`: `tasks` is a leaf → apply = execute tasks
-- `tdd`: `docs` is a leaf → but that doesn't make sense for TDD...
-
-**Pros:** No extra schema field, derived from graph
-**Cons:** Doesn't match TDD semantics (implementation is the action, not docs)
-
-### Option C: Schema-level `apply_phase` definition
-
-Add a top-level field to the schema:
-
-```yaml
-name: spec-driven
-apply_phase:
-  requires: [tasks]  # Must exist before apply
-  tracks: tasks.md   # File with checkboxes to track
-  instruction: "Work through tasks, mark complete as you go"
-```
-
-```yaml
-name: tdd
-apply_phase:
-  requires: [tests]  # Must have tests before implementing
-  tracks: null       # No checkbox tracking - just make tests pass
-  instruction: "Run tests, implement until green, refactor"
-```
-
-**Pros:** Full flexibility, schema controls its own apply semantics
-**Cons:** More complex schema format
-
-### Option D: Convention-based (artifact ID matching)
-
-If artifact ID is `tasks` or `implementation`, it's the apply target.
-
-**Pros:** Simple, no schema changes
-**Cons:** Brittle, doesn't work for custom schemas
-
-### Option E: All artifacts complete → apply available
-
-Apply becomes available when ALL schema artifacts exist. Implementation is whatever the user does after planning.
-
-**Pros:** Simple, no schema changes
-**Cons:** Doesn't guide what "apply" means for different workflows
-
----
-
-## Decision: Add `apply` block to schema.yaml
-
-Add a top-level `apply` field to schema definitions:
-
-```yaml
-name: spec-driven
-version: 1
-description: Default OpenSpec workflow
-
-artifacts:
-  # ... existing artifacts ...
-
-apply:
-  requires: [tasks]           # Artifacts that must exist before apply
-  tracks: tasks.md            # File with checkboxes for progress (optional)
-  instruction: |              # Guidance shown to agent
-    Read context files, work through pending tasks, mark complete as you go.
-    Pause if you hit blockers or need clarification.
-```
-
-```yaml
-name: tdd
-version: 1
-description: Test-driven development workflow
-
-artifacts:
-  # ... existing artifacts ...
-
-apply:
-  requires: [tests]           # Must have tests before implementing
-  tracks: null                # No checkbox tracking
-  instruction: |
-    Run tests to see failures. Implement minimal code to pass each test.
-    Refactor while keeping tests green.
-```
-
-**Key properties:**
-- `requires`: Array of artifact IDs that must exist before apply is available
-- `tracks`: Path to file with checkboxes (relative to change dir), or `null` if no tracking
-- `instruction`: Custom guidance for the apply phase
-
-**Fallback behavior:** Schemas without `apply` block default to "all artifacts must exist"
-
-## Capabilities
-
-### Modified Capabilities
-- `cli-artifact-workflow`: Apply instructions become schema-aware
-
-## Impact
-
-- **Affected code**: `src/commands/artifact-workflow.ts` (generateApplyInstructions)
-- **Schema format**: May need new `apply_phase` field
-- **Existing schemas**: Need to add apply_phase to `spec-driven` and `tdd`
-- **Backward compatible**: Schemas without apply_phase can use default behavior

package/OpenSpec-main/openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/specs/cli-artifact-workflow/spec.md

@@ -1,60 +0,0 @@
-## ADDED Requirements
-
-### Requirement: Schema Apply Block
-
-The system SHALL support an `apply` block in schema definitions that controls when and how implementation begins.
-
-#### Scenario: Schema with apply block
-
-- **WHEN** a schema defines an `apply` block
-- **THEN** the system uses `apply.requires` to determine which artifacts must exist before apply
-- **AND** uses `apply.tracks` to identify the file for progress tracking (or null if none)
-- **AND** uses `apply.instruction` for guidance shown to the agent
-
-#### Scenario: Schema without apply block
-
-- **WHEN** a schema has no `apply` block
-- **THEN** the system requires all artifacts to exist before apply is available
-- **AND** uses default instruction: "All artifacts complete. Proceed with implementation."
-
-### Requirement: Apply Instructions Command
-
-The system SHALL generate schema-aware apply instructions via `openspec instructions apply`.
-
-#### Scenario: Generate apply instructions
-
-- **WHEN** user runs `openspec instructions apply --change <id>`
-- **AND** all required artifacts (per schema's `apply.requires`) exist
-- **THEN** the system outputs:
-  - Context files from all existing artifacts
-  - Schema-specific instruction text
-  - Progress tracking file path (if `apply.tracks` is set)
-
-#### Scenario: Apply blocked by missing artifacts
-
-- **WHEN** user runs `openspec instructions apply --change <id>`
-- **AND** required artifacts are missing
-- **THEN** the system indicates apply is blocked
-- **AND** lists which artifacts must be created first
-
-#### Scenario: Apply instructions JSON output
-
-- **WHEN** user runs `openspec instructions apply --change <id> --json`
-- **THEN** the system outputs JSON with:
-  - `contextFiles`: array of paths to existing artifacts
-  - `instruction`: the apply instruction text
-  - `tracks`: path to progress file or null
-  - `applyRequires`: list of required artifact IDs
-
-## MODIFIED Requirements
-
-### Requirement: Status Command
-
-The system SHALL display artifact completion status for a change, including apply readiness.
-
-#### Scenario: Status JSON includes apply requirements
-
-- **WHEN** user runs `openspec status --change <id> --json`
-- **THEN** the system outputs JSON with:
-  - `changeName`, `schemaName`, `isComplete`, `artifacts` array
-  - `applyRequires`: array of artifact IDs needed for apply phase

package/OpenSpec-main/openspec/changes/archive/2026-01-06-make-apply-instructions-schema-aware/tasks.md

@@ -1,35 +0,0 @@
-## Prerequisites
-
-- [x] 0.1 Implement `add-per-change-schema-metadata` first (to auto-detect schema)
-
-## 1. Schema Format
-
-- [x] 1.1 Add `ApplyPhaseSchema` Zod schema to `src/core/artifact-graph/types.ts`
-- [x] 1.2 Update `SchemaYamlSchema` to include optional `apply` field
-- [x] 1.3 Export `ApplyPhase` type
-
-## 2. Update Existing Schemas
-
-- [x] 2.1 Add `apply` block to `schemas/spec-driven/schema.yaml`
-- [x] 2.2 Add `apply` block to `schemas/tdd/schema.yaml`
-
-## 3. Refactor generateApplyInstructions
-
-- [x] 3.1 Load schema via `resolveSchema(schemaName)`
-- [x] 3.2 Read `apply.requires` to determine required artifacts
-- [x] 3.3 Check artifact existence dynamically (not hardcoded paths)
-- [x] 3.4 Use `apply.tracks` for progress tracking (or skip if null)
-- [x] 3.5 Use `apply.instruction` for the instruction text
-- [x] 3.6 Build `contextFiles` from all existing artifacts in schema
-
-## 4. Handle Fallback
-
-- [x] 4.1 If schema has no `apply` block, require all artifacts to exist
-- [x] 4.2 Default instruction: "All artifacts complete. Proceed with implementation."
-
-## 5. Tests
-
-- [x] 5.1 Test apply instructions with spec-driven schema
-- [x] 5.2 Test apply instructions with tdd schema
-- [x] 5.3 Test fallback when schema has no apply block
-- [x] 5.4 Test blocked state when required artifacts missing

package/OpenSpec-main/openspec/changes/archive/2026-01-06-opsx-archive-command/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-01-07

package/OpenSpec-main/openspec/changes/archive/2026-01-06-opsx-archive-command/design.md

@@ -1,84 +0,0 @@
-## Context
-
-The experimental workflow (OPSX) provides a complete lifecycle for creating changes:
-- `/opsx:new` - Scaffold a new change with schema
-- `/opsx:continue` - Create next artifact
-- `/opsx:ff` - Fast-forward all artifacts
-- `/opsx:apply` - Implement tasks
-- `/opsx:sync` - Sync delta specs to main
-
-The missing piece is archiving. The existing `openspec archive` command works but:
-1. Applies specs programmatically (not agent-driven)
-2. Doesn't use the artifact graph for completion checking
-3. Doesn't integrate with the OPSX workflow philosophy
-
-## Goals / Non-Goals
-
-**Goals:**
-- Add `/opsx:archive` skill to complete the OPSX workflow lifecycle
-- Use artifact graph for schema-aware completion checking
-- Integrate with `/opsx:sync` for agent-driven spec syncing
-- Preserve `.openspec.yaml` schema metadata in archive
-
-**Non-Goals:**
-- Replacing the existing `openspec archive` CLI command
-- Changing how specs are applied in the CLI command
-- Modifying the artifact graph or schema system
-
-## Decisions
-
-### Decision 1: Skill-only implementation (no new CLI command)
-
-The `/opsx:archive` will be a slash command/skill only, not a new CLI command.
-
-**Rationale**: The existing `openspec archive` CLI command already handles the core archive functionality (moving to archive folder, date prefixing). The OPSX version just needs different pre-archive checks and optional sync prompting, which are agent behaviors better suited to a skill.
-
-**Alternatives considered**:
-- Adding flags to `openspec archive` (e.g., `--experimental`) - Rejected: adds complexity to CLI, harder to maintain two code paths
-- New CLI command `openspec archive-experimental` - Rejected: unnecessary duplication, agent skills are the OPSX pattern
-
-### Decision 2: Prompt for sync before archive
-
-The skill will check for unsynced delta specs and prompt the user before archiving.
-
-**Rationale**: The OPSX philosophy is agent-driven intelligent merging via `/opsx:sync`. Rather than programmatically applying specs like the regular archive command, we prompt the user to sync first if needed. This maintains workflow flexibility (user can decline and just archive).
-
-**Flow**:
-1. Check if `specs/` directory exists in the change
-2. If yes, ask: "This change has delta specs. Would you like to sync them to main specs before archiving?"
-3. If user says yes, execute `/opsx:sync` logic
-4. Proceed with archive regardless of answer
-
-### Decision 3: Use artifact graph for completion checking
-
-The skill will use `openspec status --change "<name>" --json` to check artifact completion instead of just validating proposal.md and specs.
-
-**Rationale**: The experimental workflow is schema-aware. Different schemas have different required artifacts. The artifact graph knows which artifacts are complete/incomplete for the current schema.
-
-**Behavior**:
-- Show warning if any artifacts are not `done`
-- Don't block archive (user may have valid reasons to archive early)
-- List incomplete artifacts so user can make informed decision
-
-### Decision 4: Reuse tasks.md completion check from regular archive
-
-The skill will parse tasks.md and warn about incomplete tasks, same as regular archive.
-
-**Rationale**: Task completion checking is valuable regardless of workflow. The logic is simple (count `- [ ]` vs `- [x]`) and doesn't need special OPSX handling.
-
-### Decision 5: Move change to archive/ with date prefix
-
-Same archive behavior as regular command: move to `openspec/changes/archive/YYYY-MM-DD-<name>/`.
-
-**Rationale**: Consistency with existing archive convention. The `.openspec.yaml` file moves with the change, preserving schema metadata.
-
-## Risks / Trade-offs
-
-**Risk**: Users confused about when to use `/opsx:archive` vs `openspec archive`
-→ **Mitigation**: Documentation should clarify: use `/opsx:archive` if you've been using the OPSX workflow, use `openspec archive` otherwise. Both produce the same archived result.
-
-**Risk**: Incomplete sync if user declines and has delta specs
-→ **Mitigation**: The prompt is informational; user has full control. They may want to archive without syncing (e.g., abandoned change). Log a note in output.
-
-**Trade-off**: No programmatic spec application in OPSX archive
-→ **Accepted**: This is intentional. OPSX philosophy is agent-driven merging. If user wants programmatic application, use `openspec archive` instead.

package/OpenSpec-main/openspec/changes/archive/2026-01-06-opsx-archive-command/proposal.md

@@ -1,28 +0,0 @@
-## Why
-
-The experimental workflow (OPSX) provides a schema-driven, artifact-by-artifact approach to creating changes with `/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:apply`, and `/opsx:sync`. However, there's no corresponding archive command to finalize and archive completed changes. Users must currently fall back to the regular `openspec archive` command, which doesn't integrate with the OPSX philosophy of agent-driven spec syncing and schema-aware artifact tracking.
-
-## What Changes
-
-- Add `/opsx:archive` slash command for archiving changes in the experimental workflow
-- Use artifact graph to check completion status (schema-aware) instead of just validating proposal + specs
-- Prompt for `/opsx:sync` before archiving instead of programmatically applying specs
-- Preserve `.openspec.yaml` schema metadata when moving to archive
-- Integrate with existing OPSX commands for a cohesive workflow
-
-## Capabilities
-
-### New Capabilities
-
-- `opsx-archive-skill`: Slash command and skill for archiving completed changes in the experimental workflow. Checks artifact completion via artifact graph, verifies task completion, optionally syncs specs via `/opsx:sync`, and moves the change to `archive/YYYY-MM-DD-<name>/`.
-
-### Modified Capabilities
-
-(none - this is a new skill that doesn't modify existing specs)
-
-## Impact
-
-- New file: `.claude/commands/opsx/archive.md`
-- New skill definition (generated via `openspec artifact-experimental-setup`)
-- No changes to existing archive command or other OPSX commands
-- Completes the OPSX command suite for full lifecycle management

package/OpenSpec-main/openspec/changes/archive/2026-01-06-opsx-archive-command/specs/opsx-archive-skill/spec.md

@@ -1,122 +0,0 @@
-## ADDED Requirements
-
-### Requirement: OPSX Archive Skill
-
-The system SHALL provide an `/opsx:archive` skill that archives completed changes in the experimental workflow.
-
-#### Scenario: Archive a change with all artifacts complete
-
-- **WHEN** agent executes `/opsx:archive` with a change name
-- **AND** all artifacts in the schema are complete
-- **AND** all tasks are complete
-- **THEN** the agent moves the change to `openspec/changes/archive/YYYY-MM-DD-<name>/`
-- **AND** displays success message with archived location
-
-#### Scenario: Change selection prompt
-
-- **WHEN** agent executes `/opsx:archive` without specifying a change
-- **THEN** the agent prompts user to select from available changes
-- **AND** shows only active changes (excludes archive/)
-
-### Requirement: Artifact Completion Check
-
-The skill SHALL check artifact completion status using the artifact graph before archiving.
-
-#### Scenario: Incomplete artifacts warning
-
-- **WHEN** agent checks artifact status
-- **AND** one or more artifacts have status other than `done`
-- **THEN** display warning listing incomplete artifacts
-- **AND** prompt user for confirmation to continue
-- **AND** proceed if user confirms
-
-#### Scenario: All artifacts complete
-
-- **WHEN** agent checks artifact status
-- **AND** all artifacts have status `done`
-- **THEN** proceed without warning
-
-### Requirement: Task Completion Check
-
-The skill SHALL check task completion status from tasks.md before archiving.
-
-#### Scenario: Incomplete tasks found
-
-- **WHEN** agent reads tasks.md
-- **AND** incomplete tasks are found (marked with `- [ ]`)
-- **THEN** display warning showing count of incomplete tasks
-- **AND** prompt user for confirmation to continue
-- **AND** proceed if user confirms
-
-#### Scenario: All tasks complete
-
-- **WHEN** agent reads tasks.md
-- **AND** all tasks are complete (marked with `- [x]`)
-- **THEN** proceed without task-related warning
-
-#### Scenario: No tasks file
-
-- **WHEN** tasks.md does not exist
-- **THEN** proceed without task-related warning
-
-### Requirement: Spec Sync Prompt
-
-The skill SHALL prompt to sync delta specs before archiving if specs exist.
-
-#### Scenario: Delta specs exist
-
-- **WHEN** agent checks for delta specs
-- **AND** `specs/` directory exists in the change with spec files
-- **THEN** prompt user: "This change has delta specs. Would you like to sync them to main specs before archiving?"
-- **AND** if user confirms, execute `/opsx:sync` logic
-- **AND** proceed with archive regardless of sync choice
-
-#### Scenario: No delta specs
-
-- **WHEN** agent checks for delta specs
-- **AND** no `specs/` directory or no spec files exist
-- **THEN** proceed without sync prompt
-
-### Requirement: Archive Process
-
-The skill SHALL move the change to the archive folder with date prefix.
-
-#### Scenario: Successful archive
-
-- **WHEN** archiving a change
-- **THEN** create `archive/` directory if it doesn't exist
-- **AND** generate target name as `YYYY-MM-DD-<change-name>` using current date
-- **AND** move entire change directory to archive location
-- **AND** preserve `.openspec.yaml` file in archived change
-
-#### Scenario: Archive already exists
-
-- **WHEN** target archive directory already exists
-- **THEN** fail with error message
-- **AND** suggest renaming existing archive or using different date
-
-### Requirement: Skill Output
-
-The skill SHALL provide clear feedback about the archive operation.
-
-#### Scenario: Archive complete with sync
-
-- **WHEN** archive completes after syncing specs
-- **THEN** display summary:
-  - Specs synced (from `/opsx:sync` output)
-  - Change archived to location
-  - Schema that was used
-
-#### Scenario: Archive complete without sync
-
-- **WHEN** archive completes without syncing specs
-- **THEN** display summary:
-  - Note that specs were not synced (if applicable)
-  - Change archived to location
-  - Schema that was used
-
-#### Scenario: Archive complete with warnings
-
-- **WHEN** archive completes with incomplete artifacts or tasks
-- **THEN** include note about what was incomplete
-- **AND** suggest reviewing if archive was intentional

package/OpenSpec-main/openspec/changes/archive/2026-01-06-opsx-archive-command/tasks.md

@@ -1,23 +0,0 @@
-## 1. Create Slash Command
-
-- [x] 1.1 Create `.claude/commands/opsx/archive.md` with skill definition
-- [x] 1.2 Add YAML frontmatter (name, description, category, tags)
-- [x] 1.3 Implement change selection logic (prompt if not provided)
-- [x] 1.4 Implement artifact completion check using `openspec status --json`
-- [x] 1.5 Implement task completion check (parse tasks.md for `- [ ]`)
-- [x] 1.6 Implement spec sync prompt (check for specs/ directory, offer `/opsx:sync`)
-- [x] 1.7 Implement archive process (move to archive/YYYY-MM-DD-<name>/)
-- [x] 1.8 Add output formatting for success/warning cases
-
-## 2. Regenerate Skills
-
-- [x] 2.1 Run `openspec artifact-experimental-setup` to regenerate skills
-- [x] 2.2 Verify skill appears in `.claude/skills/` directory
-
-## 3. Testing
-
-- [x] 3.1 Test `/opsx:archive` with a complete change (all artifacts, all tasks done)
-- [x] 3.2 Test `/opsx:archive` with incomplete artifacts (verify warning shown)
-- [x] 3.3 Test `/opsx:archive` with incomplete tasks (verify warning shown)
-- [x] 3.4 Test `/opsx:archive` with delta specs (verify sync prompt shown)
-- [x] 3.5 Test `/opsx:archive` without change name (verify selection prompt)

package/OpenSpec-main/openspec/changes/archive/2026-01-07-add-nix-flake-support/.openspec.yaml

@@ -1,2 +0,0 @@
-schema: spec-driven
-created: 2026-01-07

package/OpenSpec-main/openspec/changes/archive/2026-01-07-add-nix-flake-support/design.md

@@ -1,94 +0,0 @@
-## Context
-
-OpenSpec is a TypeScript CLI tool using pnpm for dependency management. The project requires Node.js ≥20.19.0. Nix uses its own build system that needs to understand how to fetch dependencies and build the project reproducibly.
-
-The Nix ecosystem has specific patterns for packaging Node.js/pnpm projects that differ from the traditional npm ecosystem.
-
-## Goals
-
-- Enable OpenSpec to be run directly via `nix run github:Fission-AI/OpenSpec`
-- Support all major platforms (Linux x86/ARM, macOS x86/ARM)
-- Use existing pnpm-lock.yaml for reproducible builds
-- Provide development environment for Nix users
-
-## Non-Goals
-
-- Replace existing npm/pnpm publishing workflow
-- Publish to nixpkgs (can be done later as separate effort)
-- Support Windows (Nix doesn't run natively on Windows)
-
-## Decisions
-
-### Use stdenv.mkDerivation instead of buildNpmPackage
-
-**Decision**: Package OpenSpec using `stdenv.mkDerivation` with pnpm hooks.
-
-**Rationale**: The zigbee2mqtt package in nixpkgs demonstrates the current best practice for pnpm projects. Using `buildNpmPackage` with pnpm requires complex configuration, while `mkDerivation` with the right hooks is more straightforward and better supported.
-
-**Alternative considered**: Using `buildNpmPackage` with `npmConfigHook = pkgs.pnpmConfigHook` - this is the older pattern and causes issues with dependency fetching.
-
-### Use fetchPnpmDeps with explicit pnpm version
-
-**Decision**: Use `pkgs.fetchPnpmDeps` with `pnpm = pkgs.pnpm_9` and `fetcherVersion = 3`.
-
-**Rationale**:
-- pnpm lockfile version 9.0 requires fetcherVersion 3
-- Explicit pnpm_9 ensures consistency between fetch and build
-- This is the documented way to handle pnpm projects in nixpkgs
-
-### Multi-platform support without flake-utils
-
-**Decision**: Implement multi-platform support using plain Nix with `nixpkgs.lib.genAttrs`.
-
-**Rationale**: Per user request, avoid extra dependencies. The `genAttrs` pattern is simple and well-understood in the Nix community.
-
-### Node.js 20 instead of latest
-
-**Decision**: Pin to nodejs_20 to match package.json engines requirement.
-
-**Rationale**: Ensures consistency with development environment and npm package requirements. Avoids potential compatibility issues with newer Node versions.
-
-## Key Implementation Details
-
-### Dependency Hash Management
-
-The `pnpmDeps.hash` field must be updated whenever dependencies change. The workflow:
-1. Set hash to fake value (all zeros)
-2. Run `nix build`
-3. Nix fails with actual hash
-4. Update flake.nix with correct hash
-
-This is standard Nix workflow for fixed-output derivations.
-
-### Build Inputs
-
-Required nativeBuildInputs:
-- `nodejs_20` - runtime
-- `npmHooks.npmInstallHook` - handles installation phase
-- `pnpmConfigHook` - configures pnpm environment
-- `pnpm_9` - pnpm executable
-
-The `dontNpmPrune = true` is important to keep all dependencies after build.
-
-## Risks / Trade-offs
-
-**[Risk]** Hash needs updating when dependencies change → **Mitigation**: Document this clearly; error message from Nix provides correct hash
-
-**[Risk]** Nix builds might lag behind npm releases → **Mitigation**: This is fine; Nix users can still use npm if they need bleeding edge
-
-**[Trade-off]** Additional maintenance burden for hash updates → **Benefit**: Better experience for Nix ecosystem users
-
-## Migration Plan
-
-1. Add flake.nix to repository
-2. Test builds on multiple platforms (can use GitHub Actions with Nix)
-3. Update README with Nix installation instructions
-4. Optionally add to CI pipeline to catch hash mismatches early
-
-No breaking changes - this is purely additive.
-
-## Open Questions
-
-- Should we add automatic hash updating to CI? (Could use nix-update-script)
-- Should we submit to nixpkgs after validation? (Separate decision)
-- Do we want to support older Node versions in flake? (Probably no - stick to package.json requirement)

package/OpenSpec-main/openspec/changes/archive/2026-01-07-add-nix-flake-support/proposal.md

@@ -1,25 +0,0 @@
-## Why
-
-OpenSpec users on NixOS or using the Nix package manager cannot easily install or run OpenSpec without going through npm. Adding a Nix flake makes OpenSpec a first-class citizen in the Nix ecosystem, enabling users to run `nix run github:Fission-AI/OpenSpec -- init` or include OpenSpec in their development environments declaratively.
-
-## What Changes
-
-- Add `flake.nix` to repository root with multi-platform support (x86_64-linux, aarch64-linux, x86_64-darwin, aarch64-darwin)
-- Package uses pnpm for dependency management (matching existing development workflow)
-- Support both direct execution via `nix run` and installation via `nix profile install`
-- Provide dev shell for contributors using Nix
-
-## Capabilities
-
-### New Capabilities
-- `nix-flake-support`: Nix flake configuration for building and running OpenSpec
-
-### Modified Capabilities
-- None
-
-## Impact
-
-- **New files**: `flake.nix` in repository root
-- **Documentation**: Should add installation instructions for Nix users
-- **CI/CD**: Could add flake checking to CI pipeline (optional)
-- **Maintenance**: Requires updating pnpmDeps hash when dependencies change