project-iris 0.0.1

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/004-standards-system/units/standards-templates/unit-brief.md

@@ -0,0 +1,394 @@
+# Unit Brief: Standards Templates
+
+## Overview
+
+Standards Templates define the output format for generated standard files. After the Master Agent gathers decisions using facilitation guides, it uses these templates to create well-structured markdown files in the memory bank.
+
+---
+
+## Scope
+
+### In Scope
+
+- Output file structure for each standard
+- Section headers and organization
+- Placeholder syntax for decision values
+- Formatting conventions
+
+### Out of Scope
+
+- What decisions exist (handled by standards-catalog)
+- How to gather decisions (handled by facilitation-guides)
+
+---
+
+## Technical Context
+
+### File Location
+
+`.irismd/aidlc/templates/standards/{standard-id}-template.md`
+
+### Output Location
+
+`memory-bank/standards/{standard-id}.md`
+
+---
+
+## Implementation Details
+
+### Template Structure
+
+Templates use placeholder syntax for dynamic content:
+
+```markdown
+# {Standard Title}
+
+## Overview
+{overview_text}
+
+## {Decision Display Name}
+{decision_choice}
+
+{decision_rationale}
+
+---
+
+## {Next Section}
+...
+```
+
+### Tech Stack Template
+
+```markdown
+# Tech Stack
+
+## Overview
+{overview - 1-2 sentences summarizing the stack}
+
+---
+
+## Languages
+{languages_choice}
+
+{languages_rationale}
+
+---
+
+## Framework
+{framework_choice}
+
+{framework_rationale}
+
+---
+
+## Database
+{database_choice | "TBD - will determine based on data needs"}
+
+{database_rationale}
+
+---
+
+## ORM / Database Client
+{orm_choice | "N/A"}
+
+{orm_rationale}
+
+---
+
+## Authentication
+{auth_choice | "TBD"}
+
+{auth_rationale}
+
+---
+
+## Infrastructure & Deployment
+{infrastructure_choice}
+
+{infrastructure_rationale}
+
+---
+
+## Package Manager
+{package_manager_choice}
+
+---
+
+## Decision Relationships
+{relationships - how choices connect, e.g., "Prisma chosen for Next.js integration"}
+```
+
+### Coding Standards Template
+
+~~~~markdown
+# Coding Standards
+
+## Overview
+Code style and quality standards for this project.
+
+---
+
+## Code Formatting
+{formatting_choice}
+
+{formatting_rationale}
+
+---
+
+## Linting
+{linting_choice}
+
+{linting_rationale}
+
+---
+
+## Naming Conventions
+
+### Files
+{file_naming}
+
+### Variables & Functions
+{variable_naming}
+
+### Classes & Types
+{class_naming}
+
+---
+
+## File & Folder Organization
+{organization_pattern}
+
+```text
+
+{folder_structure_example}
+
+```
+
+---
+
+## Testing Strategy
+{testing_approach}
+
+### Test Types
+{test_types}
+
+### Coverage Requirements
+{coverage_requirements}
+
+---
+
+## Error Handling
+{error_handling_pattern}
+
+---
+
+## Logging
+{logging_approach}
+
+---
+
+## Version Control
+
+### Commit Messages
+{commit_format}
+
+### Branch Strategy
+{branch_strategy}
+~~~~
+
+### System Architecture Template
+
+~~~~markdown
+# System Architecture
+
+## Overview
+{overview - high-level description of the system}
+
+---
+
+## Architecture Style
+{architecture_style}
+
+{style_rationale}
+
+---
+
+## Component Diagram
+
+```text
+
+{ascii_diagram}
+
+```
+
+---
+
+## API Design
+{api_design_choice}
+
+{api_rationale}
+
+---
+
+## State Management
+{state_management_choice}
+
+{state_rationale}
+
+---
+
+## Caching Strategy
+{caching_approach | "No caching required"}
+
+---
+
+## Security Patterns
+
+### Authentication
+{auth_pattern}
+
+### Authorization
+{authz_pattern}
+
+### Data Protection
+{data_protection}
+
+---
+
+## Deployment Architecture
+{deployment_description}
+~~~~
+
+### Placeholder Syntax
+
+| Syntax | Meaning |
+|--------|---------|
+| `{decision_id}` | Value of the decision |
+| `{decision_id_choice}` | Just the choice name |
+| `{decision_id_rationale}` | Just the rationale |
+| `{value \| "default"}` | Use default if value is empty |
+| `{section_if:condition}...{/section_if}` | Conditional section |
+
+### Generated Output Example
+
+After facilitation, a tech-stack.md might look like:
+
+```markdown
+# Tech Stack
+
+## Overview
+Modern TypeScript stack optimized for full-stack web development with
+serverless deployment.
+
+---
+
+## Languages
+TypeScript
+
+Node.js runtime with TypeScript for type safety, excellent tooling support,
+and seamless React integration. The team has strong TypeScript experience.
+
+---
+
+## Framework
+Next.js 14 (App Router)
+
+Full-stack React framework providing SSR, SSG, API routes, and excellent
+Vercel integration. App Router chosen for React Server Components support.
+
+---
+
+## Database
+PostgreSQL (via Supabase)
+
+Managed PostgreSQL providing real-time subscriptions, row-level security,
+and integrated authentication. Supabase chosen for quick setup and
+generous free tier.
+
+---
+
+## ORM / Database Client
+Prisma
+
+Type-safe database access with excellent Next.js integration, automatic
+migrations, and Prisma Studio for data browsing.
+
+---
+
+## Authentication
+Supabase Auth
+
+Integrated with database choice. Provides email/password, social providers
+(Google, GitHub), and magic links out of the box.
+
+---
+
+## Infrastructure & Deployment
+Vercel
+
+Optimized for Next.js with automatic deployments, edge functions, and
+preview deployments for PRs. Team already familiar with platform.
+
+---
+
+## Package Manager
+pnpm
+
+Fast, disk-efficient package manager with excellent monorepo support
+via workspaces.
+
+---
+
+## Decision Relationships
+- Supabase (database + auth) chosen as integrated platform
+- Prisma connects Next.js to Supabase PostgreSQL with type safety
+- Vercel deployment pairs naturally with Next.js
+- pnpm chosen for potential future monorepo expansion
+```
+
+---
+
+## Template Generation Process
+
+```text
+1. Load template from templates/standards/{id}-template.md
+2. For each placeholder in template:
+   - Look up value in gathered decisions
+   - Apply default if value is empty
+   - Format value according to type
+3. Process conditional sections
+4. Write to memory-bank/standards/{id}.md
+```
+
+---
+
+## Acceptance Criteria
+
+### AC-1: Template Loading
+
+- GIVEN tech-stack facilitation complete
+- WHEN template is loaded
+- THEN all placeholders are identified
+- AND template structure is valid markdown
+
+### AC-2: Placeholder Resolution
+
+- GIVEN decisions { languages: "TypeScript", languages_rationale: "Type safety..." }
+- WHEN template is processed
+- THEN {languages} is replaced with "TypeScript"
+- AND {languages_rationale} is replaced with explanation
+
+### AC-3: Default Handling
+
+- GIVEN database decision is TBD
+- WHEN template is processed
+- THEN {database | "TBD"} renders as "TBD"
+- AND output is still valid
+
+### AC-4: File Generation
+
+- GIVEN all decisions gathered and template processed
+- WHEN output is written
+- THEN file exists at memory-bank/standards/tech-stack.md
+- AND content matches processed template
+- AND markdown is valid and well-formatted

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/004-standards-system/units.md

@@ -0,0 +1,110 @@
+# Unit Decomposition: 004-standards-system
+
+## Overview
+
+The Standards System provides a three-tier architecture for creating project standards: a catalog that defines available standards, facilitation guides that help agents gather decisions, and templates for generating the final standard files.
+
+---
+
+## Units Created
+
+| Unit | Purpose | Dependencies |
+|------|---------|--------------|
+| `standards-catalog` | Registry of available standards with decisions | None |
+| `facilitation-guides` | Conversational prompts for gathering decisions | `standards-catalog` |
+| `standards-templates` | Output templates for generated standards | `facilitation-guides` |
+
+---
+
+## Dependency Graph
+
+```text
+┌─────────────────────┐
+│  standards-catalog  │
+│     (catalog.yaml)  │
+└──────────┬──────────┘
+           │ defines what to ask
+           ▼
+┌─────────────────────┐
+│ facilitation-guides │
+│    (*.guide.md)     │
+└──────────┬──────────┘
+           │ generates output using
+           ▼
+┌─────────────────────┐
+│ standards-templates │
+│  (*-template.md)    │
+└─────────────────────┘
+           │
+           ▼
+     memory-bank/standards/*.md
+        (generated output)
+```
+
+---
+
+## File Structure
+
+```text
+.irismd/aidlc/templates/standards/
+├── catalog.yaml                    # Registry of all standards
+├── tech-stack.guide.md             # Facilitation guide for tech stack
+├── coding-standards.guide.md       # Facilitation guide for code style
+├── system-architecture.guide.md    # Facilitation guide for architecture
+├── ux-guide.guide.md               # Facilitation guide for UX (optional)
+├── api-conventions.guide.md        # Facilitation guide for APIs (optional)
+├── tech-stack-template.md          # Output template
+├── coding-standards-template.md    # Output template
+└── system-architecture-template.md # Output template
+```
+
+---
+
+## Three-Tier Architecture
+
+### Tier 1: Standards Catalog
+
+Defines WHAT standards exist and WHAT decisions need to be made.
+
+### Tier 2: Facilitation Guides
+
+Defines HOW to gather each decision through conversation.
+
+### Tier 3: Standards Templates
+
+Defines the OUTPUT format for generated standards.
+
+---
+
+## Available Standards
+
+| Standard ID | Name | Importance | Required |
+|-------------|------|------------|----------|
+| `tech-stack` | Technology Stack | Critical | Yes |
+| `coding-standards` | Coding Standards | Critical | Yes |
+| `system-architecture` | System Architecture | High | Recommended |
+| `ux-guide` | UX Guide | Medium | Optional |
+| `api-conventions` | API Conventions | Medium | Optional |
+
+---
+
+## Project Types
+
+Different project types require different standards:
+
+| Project Type | Required | Recommended |
+|--------------|----------|-------------|
+| `full-stack-web` | tech-stack, coding-standards | system-architecture, ux-guide, api-conventions |
+| `backend-api` | tech-stack, coding-standards | system-architecture, api-conventions |
+| `frontend-app` | tech-stack, coding-standards | ux-guide |
+| `cli-tool` | tech-stack, coding-standards | - |
+| `library` | tech-stack, coding-standards | api-conventions |
+
+---
+
+## Artifacts Created
+
+- `004-standards-system/units.md` (this file)
+- `004-standards-system/units/standards-catalog/unit-brief.md`
+- `004-standards-system/units/facilitation-guides/unit-brief.md`
+- `004-standards-system/units/standards-templates/unit-brief.md`

package/src/iris_bundle/frameworks/iris-core/memory-bank/intents/005-testing-strategy/requirements.md

@@ -0,0 +1,188 @@
+# Intent: Testing Strategy
+
+## Overview
+
+Implement a comprehensive testing framework for irismd that addresses the unique challenges of testing CLI tools combined with markdown-based agentic workflows, handling both deterministic and non-deterministic components.
+
+---
+
+## Research Documents
+
+Detailed research, tutorials, and implementation guides are available in:
+
+| Document | Path | Description |
+|----------|------|-------------|
+| **Testing Strategy** | `memory-bank/research/test_strategy/testing-strategy.md` | Core strategy with 6-layer pyramid, developer workflows, CI/CD integration |
+| **Promptfoo Tutorial** | `memory-bank/research/test_strategy/promptfoo-tutorial.md` | General Promptfoo guide, comparisons, assertions |
+| **irismd Tutorial** | `memory-bank/research/test_strategy/promptfoo-irismd-tutorial.md` | irismd-specific testing guide, golden datasets, test fixtures |
+
+---
+
+## Technology Decisions
+
+Based on research, the following technologies have been selected:
+
+| Layer | Technology | Rationale |
+|-------|------------|-----------|
+| **Unit Tests** | Vitest | Fast, TypeScript-native, Jest-compatible |
+| **Schema/Contract** | JSON Schema (Ajv) + markdownlint | Validates YAML/MD structure without LLM |
+| **Integration** | BATS | Tests CLI commands in real shell |
+| **E2E Workflow** | Custom Node.js harness | Orchestrates multi-agent flows |
+| **Agent Behavior** | Promptfoo + OpenRouter Free | Declarative LLM testing, $0 cost |
+| **Release Validation** | Promptfoo + Grok 4.1 Fast + Human | High-quality eval, $0 cost |
+
+### LLM-as-Judge Models (All Free)
+
+| Model | Use Case |
+|-------|----------|
+| `x-ai/grok-4.1-fast:free` | Coding agents, release validation (2M context) |
+| `qwen/qwen3-coder:free` | Code-specialized evaluation |
+| `meta-llama/llama-3.3-70b-instruct:free` | High-quality reasoning |
+
+**Cost**: Entire testing stack is **$0** using OpenRouter free tier.
+
+---
+
+## Problem Statement
+
+irismd has three distinct layers requiring different testing approaches:
+
+1. **CLI Tool Layer** - Deterministic commands, installers, file operations
+2. **Markdown Specification Layer** - Schema validation, structure compliance
+3. **Agent Behavior Layer** - Non-deterministic LLM-driven outputs
+
+Traditional testing approaches fail for agent behaviors due to LLM non-determinism. A multi-layer strategy combining specification-driven testing, behavioral assertions, and LLM-as-judge evaluation is required.
+
+---
+
+## Functional Requirements
+
+### FR-1: Specification Contract Testing
+
+- FR-1.1: System SHALL validate `memory-bank.yaml` schema against JSON Schema
+- FR-1.2: System SHALL validate intent artifacts contain required sections
+- FR-1.3: System SHALL validate unit briefs follow template structure
+- FR-1.4: System SHALL validate bolt templates conform to type definitions
+- FR-1.5: System SHALL enforce markdown structure via linting rules
+
+### FR-2: CLI & Installer Testing
+
+- FR-2.1: System SHALL provide unit tests for all installer components
+- FR-2.2: System SHALL provide integration tests for slash commands via BATS
+- FR-2.3: System SHALL provide snapshot tests for generated file content
+- FR-2.4: System SHALL provide property-based tests for Memory Bank CRUD operations
+
+### FR-3: Agent Behavior Testing
+
+- FR-3.1: System SHALL support mocking LLM responses for CI/CD pipelines
+- FR-3.2: System SHALL support LLM-as-judge evaluation with configurable rubrics
+- FR-3.3: System SHALL support semantic similarity testing against golden datasets
+- FR-3.4: System SHALL support behavioral assertions (property checks, not exact matches)
+- FR-3.5: System SHALL handle test flakiness due to LLM non-determinism
+
+### FR-4: End-to-End Workflow Testing
+
+- FR-4.1: System SHALL test complete AI-DLC flows (Inception → Construction → Operations)
+- FR-4.2: System SHALL test multi-agent coordination scenarios
+- FR-4.3: System SHALL test partial completion and state recovery
+- FR-4.4: System SHALL support pre-seeded Memory Bank states for reproducibility
+
+### FR-5: Golden Dataset Management
+
+- FR-5.1: System SHALL maintain curated input/output examples per agent
+- FR-5.2: System SHALL support baseline comparison for regression detection
+- FR-5.3: System SHALL support evaluation rubrics in YAML format
+- FR-5.4: System SHALL track quality scores over time
+
+### FR-6: CI/CD Integration
+
+- FR-6.1: System SHALL run deterministic tests on every PR
+- FR-6.2: System SHALL run agent evaluation tests on merge to main
+- FR-6.3: System SHALL run comprehensive evaluation nightly
+- FR-6.4: System SHALL support human approval gates at phase transitions
+- FR-6.5: System SHALL block releases when quality thresholds are not met
+
+---
+
+## Non-Functional Requirements
+
+### NFR-1: Performance
+
+- Deterministic tests SHALL complete in under 2 minutes per PR
+- Agent evaluation tests SHALL complete in under 5 minutes for quick eval
+- Full golden dataset evaluation SHALL complete in under 30 minutes
+
+### NFR-2: Reliability
+
+- Test suite SHALL be reproducible across environments
+- Mock responses SHALL be versioned and deterministic
+- Golden dataset baselines SHALL be immutable per version
+
+### NFR-3: Maintainability
+
+- Test fixtures SHALL be organized by test layer and agent
+- Evaluation rubrics SHALL be human-readable YAML
+- Test configuration SHALL support environment overrides
+
+### NFR-4: Observability
+
+- Test results SHALL be reportable as metrics
+- Quality scores SHALL be trackable over time
+- Regression trends SHALL be visualizable in dashboards
+
+### NFR-5: Extensibility
+
+- New agents SHALL be testable without modifying test framework
+- New evaluation metrics SHALL be addable via configuration
+- Custom rubrics SHALL be definable per project
+
+---
+
+## Success Criteria
+
+- 100% of specification contracts are validated automatically
+- 100% of CLI commands have integration test coverage
+- All agents have minimum 10 golden dataset examples
+- Agent quality scores maintain > 0.85 threshold
+- Regression from baseline is detected within 1 CI run
+- Zero production bugs escape to users due to untested agent behaviors
+
+---
+
+## Acceptance Criteria
+
+### AC-1: Schema Validation
+
+- GIVEN a memory-bank.yaml file
+- WHEN schema validation runs
+- THEN all required fields are validated against JSON Schema
+
+### AC-2: CLI Testing
+
+- GIVEN an installed irismd instance
+- WHEN BATS tests execute slash commands
+- THEN commands produce expected file system state
+
+### AC-3: Agent Mock Testing
+
+- GIVEN a mocked LLM response fixture
+- WHEN agent tests run in CI
+- THEN tests are deterministic and reproducible
+
+### AC-4: Golden Dataset Evaluation
+
+- GIVEN a golden dataset with 10+ examples per agent
+- WHEN evaluation runs against current prompts
+- THEN quality scores are compared to baseline with threshold checks
+
+### AC-5: Regression Detection
+
+- GIVEN a baseline quality score of 0.90
+- WHEN prompt changes cause score to drop to 0.82
+- THEN CI pipeline fails and alerts are triggered
+
+### AC-6: E2E Workflow
+
+- GIVEN a pre-seeded Memory Bank state
+- WHEN full AI-DLC workflow executes
+- THEN all phase transitions produce valid artifacts