docs: add artifact POC analysis document

Add internal documentation for the artifact-based approach to OpenSpec
core. This document outlines design decisions, terminology, and the
philosophy behind treating dependencies as enablers rather than gates.

.gitignore

@@ -140,8 +140,6 @@ dist/
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
 
-# Internal Docs
-docs/
 
 # Claude
 .claude/

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @fission-ai/openspec
 
+## 0.17.2
+
+### Patch Changes
+
+- 455c65f: Fix `--no-interactive` flag in validate command to properly disable spinner, preventing hangs in pre-commit hooks and CI environments
+
 ## 0.17.1
 
 ### Patch Changes

docs/artifact_poc.md

@@ -0,0 +1,530 @@
+# POC-OpenSpec-Core Analysis
+
+---
+
+## Design Decisions & Terminology
+
+### Philosophy: Not a Workflow System
+
+This system is **not** a workflow engine. It's an **artifact tracker with dependency awareness**.
+
+| What it's NOT | What it IS |
+|---------------|------------|
+| Linear step-by-step progression | Exploratory, iterative planning |
+| Bureaucratic checkpoints | Enablers that unlock possibilities |
+| "You must complete step 1 first" | "Here's what you could create now" |
+| Form-filling | Fluid document creation |
+
+**Key insight:** Dependencies are *enablers*, not *gates*. You can't meaningfully write a design document if there's no proposal to design from - that's not bureaucracy, it's logic.
+
+### Terminology
+
+| Term | Definition | Example |
+|------|------------|---------|
+| **Change** | A unit of work being planned (feature, refactor, migration) | `openspec/changes/add-auth/` |
+| **Schema** | An artifact graph definition (what artifacts exist, their dependencies) | `schemas/spec-driven.yaml` |
+| **Artifact** | A node in the graph (a document to create) | `proposal`, `design`, `specs` |
+| **Template** | Instructions/guidance for creating an artifact | `templates/proposal.md` |
+
+### Hierarchy
+
+```
+Schema (defines) ──→ Artifacts (guided by) ──→ Templates
+```
+
+- **Schema** = the artifact graph (what exists, dependencies)
+- **Artifact** = a document to produce
+- **Template** = instructions for creating that artifact
+
+### Schema Variations
+
+Schemas can vary across multiple dimensions:
+
+| Dimension | Examples |
+|-----------|----------|
+| Philosophy | `spec-driven`, `tdd`, `prototype-first` |
+| Version | `v1`, `v2`, `v3` |
+| Language | `en`, `zh`, `es` |
+| Custom | `team-alpha`, `experimental` |
+
+### Template Inheritance (2 Levels Max)
+
+```
+.openspec/
+├── templates/                 # Shared (Level 1)
+│   ├── proposal.md
+│   ├── design.md
+│   └── specs.md
+│
+└── schemas/
+    └── tdd/
+        ├── schema.yaml
+        └── templates/         # Overrides (Level 2)
+            └── tests.md       # TDD-specific
+```
+
+**Rules:**
+- Shared templates are the default
+- Schema-specific templates override OR add new
+- A CLI command shows resolved paths (no guessing)
+- No inheritance between schemas (copy if you need to diverge)
+- Max 2 levels - no deeper inheritance chains
+
+**Why this matters:**
+- Avoids "where does this come from?" debugging
+- No implicit magic that works until it doesn't
+- Clear boundaries between shared and specific
+
+---
+
+## Executive Summary
+
+This is an **artifact tracker with dependency awareness** that guides iterative development through a structured artifact pipeline. The core innovation is using the **filesystem as a database** - artifact completion is detected by file existence, making the system stateless and version-control friendly.
+
+The system answers:
+- "What artifacts exist for this change?"
+- "What could I create next?" (not "what must I create")
+- "What's blocking X?" (informational, not prescriptive)
+
+---
+
+## Core Components
+
+### 1. ArtifactGraph
+
+The dependency graph engine.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Model artifacts as a DAG | Artifact with `requires: string[]` |
+| Track completion state | Sets for `completed`, `in_progress`, `failed` |
+| Calculate build order | Kahn's algorithm (topological sort) |
+| Find ready artifacts | Check if all dependencies are in `completed` set |
+
+**Key Data Structures:**
+
+```
+Artifact {
+  id: string
+  generates: string        // e.g., "proposal.md" or "specs/*.md"
+  description: string
+  instruction: string      // path to template
+  requires: string[]       // artifact IDs this depends on
+}
+
+ArtifactState {
+  completed: Set<string>
+  inProgress: Set<string>
+  failed: Set<string>
+}
+
+ArtifactGraph {
+  artifacts: Map<string, Artifact>
+}
+```
+
+**Key Methods:**
+- `fromYaml(path)` - Load artifact definitions from YAML
+- `getNextArtifacts(state)` - Find artifacts ready to create
+- `getBuildOrder()` - Topological sort of all artifacts
+- `isComplete(state)` - Check if all artifacts done
+
+---
+
+### 2. ChangeManager
+
+Multi-change orchestration layer. **CLI is fully deterministic** - no "active change" tracking.
+
+| Responsibility | Approach |
+|----------------|----------|
+| CRUD changes | Create dirs under `openspec/changes/<name>/` |
+| Template fallback | Schema-specific → Shared (2 levels max) |
+
+**Key Paths:**
+
+```
+.openspec/schemas/         → Schema definitions (artifact graphs)
+.openspec/templates/       → Shared instruction templates
+openspec/changes/<name>/   → Change instances with artifacts
+```
+
+**Key Methods:**
+- `isInitialized()` - Check for `.openspec/` existence
+- `listChanges()` - List all changes in `openspec/changes/`
+- `createChange(name, description)` - Create new change directory
+- `getChangePath(name)` - Get path to a change directory
+- `getSchemaPath(schemaName?)` - Find schema with fallback
+- `getTemplatePath(artifactId, schemaName?)` - Find template (schema → shared)
+
+**Note:** No `getActiveChange()`, `setActiveChange()`, or `resolveChange()` - the agent infers which change from conversation context and passes it explicitly to CLI commands.
+
+---
+
+### 3. InstructionLoader
+
+State detection and instruction enrichment.
+
+| Responsibility | Approach |
+|----------------|----------|
+| Detect artifact completion | Scan filesystem, support glob patterns |
+| Build dynamic context | Gather dependency status, change info |
+| Enrich templates | Inject context into base templates |
+| Generate status reports | Formatted markdown with progress |
+
+**Key Class - ChangeState:**
+
+```
+ChangeState {
+  changeName: string
+  changeDir: string
+  graph: ArtifactGraph
+  state: ArtifactState
+
+  // Methods
+  getNextSteps(): string[]
+  getStatus(artifactId): ArtifactStatus
+  isComplete(): boolean
+}
+```
+
+**Key Functions:**
+- `getEnrichedInstructions(artifactId, projectRoot, changeName?)` - Main entry point
+- `getChangeStatus(projectRoot, changeName?)` - Formatted status report
+- `resolveTemplatePath(artifactId, schemaName?)` - 2-level fallback
+
+---
+
+### 4. CLI
+
+User interface layer. **All commands are deterministic** - require explicit `--change` parameter.
+
+| Command | Function |
+|---------|----------|
+| `status --change <id>` | Show change progress |
+| `next --change <id>` | Show artifacts ready to create |
+| `instructions <artifact> --change <id>` | Get enriched instructions for artifact |
+| `list` | List all changes |
+| `new <name>` | Create change |
+| `init` | Initialize structure |
+| `templates --change <id>` | Show resolved template paths |
+
+**Note:** Commands that operate on a change require `--change`. Missing parameter → error with list of available changes. Agent infers the change from conversation and passes it explicitly.
+
+---
+
+### 5. Claude Commands
+
+Integration layer for Claude Code. **Operational commands only** - artifact creation via natural language.
+
+| Command | Purpose |
+|---------|---------|
+| `/status` | Show change progress |
+| `/next` | Show what's ready to create |
+| `/run [artifact]` | Execute a specific step (power users) |
+| `/list` | List all changes |
+| `/new <name>` | Create a new change |
+| `/init` | Initialize structure |
+
+**Artifact creation:** Users say "create the proposal" or "write the tests" in natural language. The agent:
+1. Infers change from conversation (confirms if uncertain)
+2. Infers artifact from request
+3. Calls CLI with explicit `--change` parameter
+4. Creates artifact following instructions
+
+This works for ANY artifact in ANY schema - no new slash commands needed when schemas change.
+
+**Note:** Legacy commands (`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`) exist in the main project for backward compatibility but are separate from this architecture.
+
+---
+
+## Component Dependency Graph
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     PRESENTATION LAYER                       │
+│  ┌──────────────┐                    ┌────────────────────┐ │
+│  │     CLI      │ ←─shell exec───────│ Claude Commands    │ │
+│  └──────┬───────┘                    └────────────────────┘ │
+└─────────┼───────────────────────────────────────────────────┘
+          │ imports
+          ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    ORCHESTRATION LAYER                       │
+│  ┌────────────────────┐        ┌──────────────────────────┐ │
+│  │ InstructionLoader  │───────▶│    ChangeManager         │ │
+│  │                    │ uses   │                          │ │
+│  └─────────┬──────────┘        └──────────────────────────┘ │
+└────────────┼────────────────────────────────────────────────┘
+             │ uses
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                      CORE LAYER                              │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │               ArtifactGraph                          │   │
+│  │                                                      │   │
+│  │  Artifact ←────── ArtifactState                      │   │
+│  │  (data)           (runtime state)                    │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+             ▲
+             │ reads from
+             ▼
+┌─────────────────────────────────────────────────────────────┐
+│                   PERSISTENCE LAYER                          │
+│  ┌──────────────────┐   ┌────────────────────────────────┐  │
+│  │  YAML Config     │   │  Filesystem Artifacts          │  │
+│  │  - config.yaml   │   │  - proposal.md, design.md      │  │
+│  │  - schema.yaml   │   │  - specs/*.md, tasks.md        │  │
+│  └──────────────────┘   └────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Design Patterns
+
+### 1. Filesystem as Database
+
+No SQLite, no JSON state files. The existence of `proposal.md` means proposal is complete.
+
+```
+// State detection is just file existence checking
+if (exists(artifactPath)) {
+  completed.add(artifactId)
+}
+```
+
+### 2. Deterministic CLI, Inferring Agent
+
+**CLI layer:** Always deterministic - requires explicit `--change` parameter.
+
+```
+openspec status --change add-auth     # explicit, works
+openspec status                        # error: "No change specified"
+```
+
+**Agent layer:** Infers from conversation, confirms if uncertain, passes explicit `--change`.
+
+This separation means:
+- CLI is pure, testable, no state to corrupt
+- Agent handles all "smartness"
+- No config.yaml tracking of "active change"
+
+### 3. Two-Level Template Fallback
+
+```
+schema-specific/templates/proposal.md
+    ↓ (not found)
+.openspec/templates/proposal.md (shared)
+    ↓ (not found)
+Error (no silent fallback to avoid confusion)
+```
+
+### 4. Glob Pattern Support
+
+`specs/*.md` allows multiple files to satisfy a single artifact:
+
+```
+if (artifact.generates.includes("*")) {
+  const parentDir = changeDir / patternParts[0]
+  if (exists(parentDir) && hasFiles(parentDir)) {
+    completed.add(artifactId)
+  }
+}
+```
+
+### 5. Stateless State Detection
+
+Every command re-scans the filesystem. No cached state to corrupt.
+
+---
+
+## Artifact Pipeline (Default Schema)
+
+The default `spec-driven` schema:
+
+```
+┌──────────┐
+│ proposal │  (no dependencies)
+└────┬─────┘
+     │
+     ▼
+┌──────────┐
+│  specs   │  (requires: proposal)
+└────┬─────┘
+     │
+     ├──────────────┐
+     ▼              ▼
+┌──────────┐   ┌──────────┐
+│  design  │   │          │
+│          │◄──┤ proposal │
+└────┬─────┘   └──────────┘
+     │         (requires: proposal, specs)
+     ▼
+┌──────────┐
+│  tasks   │  (requires: design)
+└──────────┘
+```
+
+Other schemas (TDD, prototype-first) would have different graphs.
+
+---
+
+## Implementation Order
+
+Structured as **vertical slices** - each slice is independently testable.
+
+---
+
+### Slice 1: "What's Ready?" (Core Query)
+
+**Combines:** Types + Graph + State Detection
+
+```
+Input:  schema YAML path + change directory
+Output: {
+  completed: ['proposal'],
+  ready: ['specs'],
+  blocked: ['design', 'tasks'],
+  buildOrder: ['proposal', 'specs', 'design', 'tasks']
+}
+```
+
+**Testable behaviors:**
+- Parse schema YAML → returns correct artifact graph
+- Compute build order (topological sort) → correct ordering
+- Empty directory → only root artifacts (no dependencies) are ready
+- Directory with `proposal.md` → `specs` becomes ready
+- Directory with `specs/foo.md` → glob pattern detected as complete
+- All artifacts present → `isComplete()` returns true
+
+---
+
+### Slice 2: "Multi-Change Management"
+
+**Delivers:** CRUD for changes, path resolution
+
+**Testable behaviors:**
+- `createChange('add-auth')` → creates directory + README
+- `listChanges()` → returns directory names
+- `getChangePath('add-auth')` → returns correct path
+- Missing change → clear error message
+
+---
+
+### Slice 3: "Get Instructions" (Enrichment)
+
+**Delivers:** Template resolution + context injection
+
+**Testable behaviors:**
+- Template fallback: schema-specific → shared → error
+- Context injection: completed deps show ✓, missing show ✗
+- Output path shown correctly based on change directory
+
+---
+
+### Slice 4: "CLI + Integration"
+
+**Delivers:** Full command interface
+
+**Testable behaviors:**
+- Each command produces expected output
+- Commands compose correctly (status → next → instructions flow)
+- Error handling for missing changes, invalid artifacts, etc.
+
+---
+
+## Directory Structure
+
+```
+.openspec/
+├── schemas/                       # Schema definitions
+│   ├── spec-driven.yaml           # Default: proposal → specs → design → tasks
+│   ├── spec-driven-v2.yaml        # Version 2
+│   ├── tdd.yaml                   # TDD: tests → implementation → docs
+│   └── tdd/
+│       └── templates/             # TDD-specific template overrides
+│           └── tests.md
+│
+└── templates/                     # Shared instruction templates
+    ├── proposal.md
+    ├── design.md
+    ├── specs.md
+    └── tasks.md
+
+openspec/
+└── changes/                       # Change instances
+    ├── add-auth/
+    │   ├── README.md
+    │   ├── proposal.md            # Created artifacts
+    │   ├── design.md
+    │   └── specs/
+    │       └── *.md
+    │
+    └── refactor-db/
+        └── ...
+
+.claude/
+├── settings.local.json            # Permissions
+└── commands/                      # Slash commands
+    └── *.md
+```
+
+---
+
+## Schema YAML Format
+
+```yaml
+# .openspec/schemas/spec-driven.yaml
+name: spec-driven
+version: 1
+description: Specification-driven development
+
+artifacts:
+  - id: proposal
+    generates: "proposal.md"
+    description: "Create project proposal document"
+    template: "proposal.md"          # resolves via 2-level fallback
+    requires: []
+
+  - id: specs
+    generates: "specs/*.md"          # glob pattern
+    description: "Create technical specification documents"
+    template: "specs.md"
+    requires:
+      - proposal
+
+  - id: design
+    generates: "design.md"
+    description: "Create design document"
+    template: "design.md"
+    requires:
+      - proposal
+      - specs
+
+  - id: tasks
+    generates: "tasks.md"
+    description: "Create tasks breakdown document"
+    template: "tasks.md"
+    requires:
+      - design
+```
+
+---
+
+## Summary
+
+| Layer | Component | Responsibility |
+|-------|-----------|----------------|
+| Core | ArtifactGraph | Pure dependency logic (no I/O) |
+| Core | ChangeManager | Multi-change orchestration |
+| Core | InstructionLoader | State detection + enrichment |
+| Presentation | CLI | Thin command wrapper |
+| Integration | Claude Commands | AI assistant glue |
+
+**Key Principles:**
+- **Filesystem IS the database** - stateless, version-control friendly
+- **Dependencies are enablers** - show what's possible, don't force order
+- **Deterministic CLI, inferring agent** - CLI requires explicit `--change`, agent infers from context
+- **2-level template inheritance** - shared + override, no deeper
+- **Schemas are versioned** - support variations by philosophy, version, language

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fission-ai/openspec",
-  "version": "0.17.1",
+  "version": "0.17.2",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",

src/commands/validate.ts

@@ -1,7 +1,7 @@
 import ora from 'ora';
 import path from 'path';
 import { Validator } from '../core/validation/validator.js';
-import { isInteractive } from '../utils/interactive.js';
+import { isInteractive, resolveNoInteractive } from '../utils/interactive.js';
 import { getActiveChangeIds, getSpecIds } from '../utils/item-discovery.js';
 import { nearestMatches } from '../utils/match.js';
 
@@ -15,6 +15,7 @@ interface ExecuteOptions {
   strict?: boolean;
   json?: boolean;
   noInteractive?: boolean;
+  interactive?: boolean; // Commander sets this to false when --no-interactive is used
   concurrency?: string;
 }
 
@@ -35,7 +36,7 @@ export class ValidateCommand {
       await this.runBulkValidation({
         changes: !!options.all || !!options.changes,
         specs: !!options.all || !!options.specs,
-      }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency });
+      }, { strict: !!options.strict, json: !!options.json, concurrency: options.concurrency, noInteractive: resolveNoInteractive(options) });
       return;
     }
 
@@ -180,8 +181,8 @@ export class ValidateCommand {
     bullets.forEach(b => console.error(`  ${b}`));
   }
 
-  private async runBulkValidation(scope: { changes: boolean; specs: boolean }, opts: { strict: boolean; json: boolean; concurrency?: string }): Promise<void> {
-    const spinner = !opts.json ? ora('Validating...').start() : undefined;
+  private async runBulkValidation(scope: { changes: boolean; specs: boolean }, opts: { strict: boolean; json: boolean; concurrency?: string; noInteractive?: boolean }): Promise<void> {
+    const spinner = !opts.json && !opts.noInteractive ? ora('Validating...').start() : undefined;
     const [changeIds, specIds] = await Promise.all([
       scope.changes ? getActiveChangeIds() : Promise.resolve<string[]>([]),
       scope.specs ? getSpecIds() : Promise.resolve<string[]>([]),

src/utils/interactive.ts

@@ -1,4 +1,4 @@
-type InteractiveOptions = {
+export type InteractiveOptions = {
   /**
    * Explicit "disable prompts" flag passed by internal callers.
    */
@@ -9,7 +9,12 @@ type InteractiveOptions = {
   interactive?: boolean;
 };
 
-function resolveNoInteractive(value?: boolean | InteractiveOptions): boolean {
+/**
+ * Resolves whether non-interactive mode is requested.
+ * Handles both explicit `noInteractive: true` and Commander.js style `interactive: false`.
+ * Use this helper instead of manually checking options.noInteractive to avoid bugs.
+ */
+export function resolveNoInteractive(value?: boolean | InteractiveOptions): boolean {
   if (typeof value === 'boolean') return value;
   return value?.noInteractive === true || value?.interactive === false;
 }
@@ -17,6 +22,8 @@ function resolveNoInteractive(value?: boolean | InteractiveOptions): boolean {
 export function isInteractive(value?: boolean | InteractiveOptions): boolean {
   if (resolveNoInteractive(value)) return false;
   if (process.env.OPEN_SPEC_INTERACTIVE === '0') return false;
+  // Respect the standard CI environment variable (set by GitHub Actions, GitLab CI, Travis, etc.)
+  if ('CI' in process.env) return false;
   return !!process.stdin.isTTY;
 }
 

test/commands/validate.test.ts

@@ -130,4 +130,18 @@ describe('top-level validate command', () => {
     const result = await runCLI(['validate', changeId], { cwd: testDir });
     expect(result.exitCode).toBe(0);
   });
+
+  it('respects --no-interactive flag passed via CLI', async () => {
+    // This test ensures Commander.js --no-interactive flag is correctly parsed
+    // and passed to the validate command. The flag sets options.interactive = false
+    // (not options.noInteractive = true) due to Commander.js convention.
+    const result = await runCLI(['validate', '--specs', '--no-interactive'], {
+      cwd: testDir,
+      // Don't set OPEN_SPEC_INTERACTIVE to ensure we're testing the flag itself
+      env: { ...process.env, OPEN_SPEC_INTERACTIVE: undefined },
+    });
+    expect(result.exitCode).toBe(0);
+    // Should complete without hanging and without prompts
+    expect(result.stderr).not.toContain('What would you like to validate?');
+  });
 });

test/utils/interactive.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { isInteractive, resolveNoInteractive, InteractiveOptions } from '../../src/utils/interactive.js';
+
+describe('interactive utilities', () => {
+  let originalOpenSpecInteractive: string | undefined;
+  let originalCI: string | undefined;
+  let originalStdinIsTTY: boolean | undefined;
+
+  beforeEach(() => {
+    // Save original environment
+    originalOpenSpecInteractive = process.env.OPEN_SPEC_INTERACTIVE;
+    originalCI = process.env.CI;
+    originalStdinIsTTY = process.stdin.isTTY;
+
+    // Clear environment for clean testing
+    delete process.env.OPEN_SPEC_INTERACTIVE;
+    delete process.env.CI;
+  });
+
+  afterEach(() => {
+    // Restore original environment
+    if (originalOpenSpecInteractive !== undefined) {
+      process.env.OPEN_SPEC_INTERACTIVE = originalOpenSpecInteractive;
+    } else {
+      delete process.env.OPEN_SPEC_INTERACTIVE;
+    }
+    if (originalCI !== undefined) {
+      process.env.CI = originalCI;
+    } else {
+      delete process.env.CI;
+    }
+    // Restore stdin.isTTY
+    Object.defineProperty(process.stdin, 'isTTY', {
+      value: originalStdinIsTTY,
+      writable: true,
+      configurable: true,
+    });
+  });
+
+  describe('resolveNoInteractive', () => {
+    it('should return true when noInteractive is true', () => {
+      expect(resolveNoInteractive({ noInteractive: true })).toBe(true);
+    });
+
+    it('should return true when interactive is false (Commander.js style)', () => {
+      // This is how Commander.js handles --no-interactive flag
+      expect(resolveNoInteractive({ interactive: false })).toBe(true);
+    });
+
+    it('should return false when noInteractive is false', () => {
+      expect(resolveNoInteractive({ noInteractive: false })).toBe(false);
+    });
+
+    it('should return false when interactive is true', () => {
+      expect(resolveNoInteractive({ interactive: true })).toBe(false);
+    });
+
+    it('should return false for empty options object', () => {
+      expect(resolveNoInteractive({})).toBe(false);
+    });
+
+    it('should return false for undefined', () => {
+      expect(resolveNoInteractive(undefined)).toBe(false);
+    });
+
+    it('should handle boolean value true', () => {
+      expect(resolveNoInteractive(true)).toBe(true);
+    });
+
+    it('should handle boolean value false', () => {
+      expect(resolveNoInteractive(false)).toBe(false);
+    });
+
+    it('should prioritize noInteractive over interactive when both set', () => {
+      // noInteractive: true should win
+      expect(resolveNoInteractive({ noInteractive: true, interactive: true })).toBe(true);
+      // If noInteractive is false, check interactive
+      expect(resolveNoInteractive({ noInteractive: false, interactive: false })).toBe(true);
+    });
+  });
+
+  describe('isInteractive', () => {
+    it('should return false when noInteractive is true', () => {
+      expect(isInteractive({ noInteractive: true })).toBe(false);
+    });
+
+    it('should return false when interactive is false (Commander.js --no-interactive)', () => {
+      expect(isInteractive({ interactive: false })).toBe(false);
+    });
+
+    it('should return false when OPEN_SPEC_INTERACTIVE env var is 0', () => {
+      process.env.OPEN_SPEC_INTERACTIVE = '0';
+      Object.defineProperty(process.stdin, 'isTTY', { value: true, writable: true, configurable: true });
+      expect(isInteractive({})).toBe(false);
+    });
+
+    it('should return false when CI env var is set', () => {
+      process.env.CI = 'true';
+      Object.defineProperty(process.stdin, 'isTTY', { value: true, writable: true, configurable: true });
+      expect(isInteractive({})).toBe(false);
+    });
+
+    it('should return false when CI env var is set to any value', () => {
+      // CI can be set to any value, not just "true"
+      process.env.CI = '1';
+      Object.defineProperty(process.stdin, 'isTTY', { value: true, writable: true, configurable: true });
+      expect(isInteractive({})).toBe(false);
+    });
+
+    it('should return false when stdin is not a TTY', () => {
+      Object.defineProperty(process.stdin, 'isTTY', { value: false, writable: true, configurable: true });
+      expect(isInteractive({})).toBe(false);
+    });
+
+    it('should return true when stdin is TTY and no flags disable it', () => {
+      Object.defineProperty(process.stdin, 'isTTY', { value: true, writable: true, configurable: true });
+      expect(isInteractive({})).toBe(true);
+    });
+
+    it('should return true when stdin is TTY and options are undefined', () => {
+      Object.defineProperty(process.stdin, 'isTTY', { value: true, writable: true, configurable: true });
+      expect(isInteractive(undefined)).toBe(true);
+    });
+  });
+});