@plures/praxis 1.4.4 → 2.0.3

package/docs/README.md

@@ -1,81 +1,77 @@
-# Praxis Documentation
+# Praxis 2.0 Documentation
 
-Welcome to the official Praxis documentation! Praxis is the full-stack application framework for the Plures ecosystem, providing a complete solution for building modern, local-first, distributed applications.
+Welcome to the official Praxis documentation. Praxis is the full-stack declarative application framework for the Plures ecosystem — typed logic, reactive state, local-first data, and visual tooling for Svelte, Node, and the browser.
 
-## 🐕 Dogfooding Plures Tools
-
-**Start here for dogfooding:** [Dogfooding Index](./DOGFOODING_INDEX.md)
-
-We actively dogfood all Plures tools during development. Key resources:
-- [Quick Start Guide](./DOGFOODING_QUICK_START.md) - Get started in 5 minutes
-- [Dogfooding Checklist](./DOGFOODING_CHECKLIST.md) - Daily/weekly/monthly workflows
-- [Plures Tools Inventory](./PLURES_TOOLS_INVENTORY.md) - All available tools
-- [Workflow Examples](./examples/DOGFOODING_WORKFLOW_EXAMPLE.md) - See it in action
+> **New to Praxis?** Start with the [Getting Started guide](../GETTING_STARTED.md).
+> **Upgrading from 1.x?** See the [Migration Guide](../MIGRATION_GUIDE.md).
 
 ## Quick Start
 
 ```bash
-# Install Praxis
 npm install @plures/praxis
-
-# Create a new app
 npx praxis create app my-app
-cd my-app
-npm install
-
-# Start development
-npm run dev
 ```
 
 ## Documentation Index
 
 ### Core Concepts
 
-| Document                                               | Description                                  |
-| ------------------------------------------------------ | -------------------------------------------- |
-| [What is Praxis](./core/what-is-praxis.md)             | Overview of Praxis and its core philosophy   |
-| [Praxis-Core API](./core/praxis-core-api.md)           | Stable API surface and guarantees            |
-| [Extending Praxis-Core](./core/extending-praxis-core.md) | Extension guidelines without breaking changes |
-| [Schema Model](./core/schema-model.md)                 | Understanding the Praxis Schema Format (PSF) |
-| [Logic Engine](./core/logic-engine.md)                 | Facts, events, rules, and constraints        |
-| [UI Generation](./core/ui-generation.md)               | Automatic component generation from schemas  |
-| [PluresDB Integration](./core/pluresdb-integration.md) | Local-first data with reactive storage       |
-| [Code ↔ Canvas Sync](./core/code-canvas-sync.md)      | Bidirectional synchronization                |
-| [CLI Usage](./core/cli-usage.md)                       | Command-line interface reference             |
-| [Building Extensions](./core/building-extensions.md)   | Extending Praxis functionality               |
+| Document | Description |
+|----------|-------------|
+| [What is Praxis](./core/what-is-praxis.md) | Overview and philosophy |
+| [Praxis-Core API](./core/praxis-core-api.md) | Stable API surface and guarantees |
+| [Extending Praxis-Core](./core/extending-praxis-core.md) | Extension guidelines |
+| [Schema Model](./core/schema-model.md) | Praxis Schema Format (PSF) |
+| [Logic Engine](./core/logic-engine.md) | Facts, events, rules, and constraints |
+| [UI Generation](./core/ui-generation.md) | Component generation from schemas |
+| [PluresDB Integration](./core/pluresdb-integration.md) | Local-first data with reactive storage |
+| [Code ↔ Canvas Sync](./core/code-canvas-sync.md) | Bidirectional synchronization |
+| [CLI Usage](./core/cli-usage.md) | Command-line interface reference |
+| [Building Extensions](./core/building-extensions.md) | Extending Praxis |
 
 ### Guides
 
-| Guide                                                         | Description                         |
-| ------------------------------------------------------------- | ----------------------------------- |
-| [Getting Started](./guides/getting-started.md)                | First steps with Praxis             |
-| [Svelte Integration](./guides/svelte-integration.md)          | Using Praxis with Svelte 5          |
-| [Canvas](./guides/canvas.md)                                  | Visual development with CodeCanvas  |
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](./guides/getting-started.md) | First steps with Praxis |
+| [Svelte Integration](./guides/svelte-integration.md) | Using Praxis with Svelte 5 |
+| [Canvas](./guides/canvas.md) | Visual development with CodeCanvas |
 | [History & State Patterns](./guides/history-state-pattern.md) | Undo/redo and time-travel debugging |
-| [Parallel State Patterns](./guides/parallel-state-pattern.md) | Managing parallel state machines    |
-| [Orchestration](./guides/orchestration.md)                    | Distributed system coordination     |
+| [Parallel State Patterns](./guides/parallel-state-pattern.md) | Managing parallel state machines |
+| [Orchestration](./guides/orchestration.md) | Distributed system coordination |
+| [CI/CD Pipeline](./guides/cicd-pipeline.md) | Continuous integration setup |
 
 ### Tutorials
 
-| Tutorial                                           | Description                      |
-| -------------------------------------------------- | -------------------------------- |
-| [Build Your First App](./tutorials/first-app.md)   | Step-by-step beginner tutorial   |
-| [Todo with PluresDB](./tutorials/todo-pluresdb.md) | Local-first todo application     |
-| [Form Builder](./tutorials/form-builder.md)        | Dynamic form creation            |
-| [E-commerce Cart](./tutorials/ecommerce-cart.md)   | Shopping cart with checkout flow |
+| Tutorial | Description |
+|----------|-------------|
+| [Build Your First App](./tutorials/first-app.md) | Step-by-step beginner tutorial |
+| [Todo with PluresDB](./tutorials/todo-pluresdb.md) | Local-first todo application |
+| [Form Builder](./tutorials/form-builder.md) | Dynamic form creation |
+| [E-commerce Cart](./tutorials/ecommerce-cart.md) | Shopping cart with checkout flow |
+
+### Decision Ledger
+
+| Resource | Description |
+|----------|-------------|
+| [Dogfooding Guide](./decision-ledger/DOGFOODING.md) | Decision Ledger workflow |
+| [Behavior Ledger](./decision-ledger/BEHAVIOR_LEDGER.md) | Rule/constraint change log |
+| [Contract Index](./decision-ledger/contract-index.json) | Machine-readable contract inventory |
 
 ### Examples
 
-| Example                                     | Description                  |
-| ------------------------------------------- | ---------------------------- |
-| [Hero Shop](../examples/hero-shop/)         | Full e-commerce application  |
-| [Todo](../examples/todo/)                   | Minimal todo application     |
-| [Form Builder](../examples/form-builder/)   | Dynamic form builder         |
-| [Offline Chat](../examples/offline-chat/)   | Local-first chat application |
-| [Terminal Node](../examples/terminal-node/) | Self-orchestrating node      |
-| [Cloud Sync](../examples/cloud-sync/)       | Multi-client synchronization |
+| Example | Description |
+|---------|-------------|
+| [Unified App](../examples/unified-app/) | `createApp()` with rules and Mermaid docs |
+| [Hero Shop](../examples/hero-shop/) | Full e-commerce application |
+| [Todo](../examples/todo/) | Minimal todo application |
+| [Form Builder](../examples/form-builder/) | Dynamic form builder |
+| [Offline Chat](../examples/offline-chat/) | Local-first chat application |
+| [Terminal Node](../examples/terminal-node/) | Command execution with YAML schemas |
+| [Cloud Sync](../examples/cloud-sync/) | Multi-client synchronization |
+| [Decision Ledger](../examples/decision-ledger/) | Contracts, validation, SARIF output |
 
-## Architecture Overview
+## Architecture
 
 ```mermaid
 flowchart TB
@@ -108,59 +104,19 @@ flowchart TB
     Engine --> StateDocs
 ```
 
-## Key Features
-
-### 🎯 Schema-Driven Development
-
-Define your entire application in PSF (Praxis Schema Format), then generate everything else.
-
-### ⚡ Logic Engine
-
-Pure, functional business logic with facts, events, rules, and constraints.
-
-### 🧩 Component Generation
-
-Automatically generate Svelte components from your schemas.
-
-### 📱 Local-First
-
-Built-in PluresDB integration for offline-capable, reactive data storage.
-
-### 🎨 Visual Development
-
-CodeCanvas provides visual schema and logic editing.
+## Dogfooding
 
-### 📚 Auto-Documentation
+We actively dogfood all Plures tools during development:
 
-State-Docs generates documentation automatically from schemas.
+- [Dogfooding Index](./DOGFOODING_INDEX.md) — overview
+- [Quick Start](./DOGFOODING_QUICK_START.md) — get started in 5 minutes
+- [Checklist](./DOGFOODING_CHECKLIST.md) — daily/weekly/monthly workflows
+- [Tools Inventory](./PLURES_TOOLS_INVENTORY.md) — all available tools
+- [Workflow Example](./examples/DOGFOODING_WORKFLOW_EXAMPLE.md) — see it in action
 
-### 🌐 Cross-Platform
+## 1.x Documentation Archive
 
-Deploy to web, desktop (Tauri), and mobile from a single codebase.
-
-### 🔄 Real-Time Sync
-
-Praxis Cloud provides sync across devices and users.
-
-## Installation Options
-
-### npm
-
-```bash
-npm install @plures/praxis
-```
-
-### Deno
-
-```typescript
-import { createPraxisEngine } from 'jsr:@plures/praxis';
-```
-
-### C# (.NET)
-
-```bash
-dotnet add package Plures.Praxis
-```
+Historical documentation from Praxis 1.x development is preserved in [archive/1.x/](./archive/1.x/).
 
 ## Community
 

package/docs/archive/1.x/CONVERSATIONS_IMPLEMENTATION.md

@@ -0,0 +1,207 @@
+# Praxis Conversations Subsystem Implementation
+
+## Overview
+
+This document summarizes the implementation of the **praxis-conversations** subsystem, a deterministic-first conversation ingestion pipeline integrated into the Praxis framework.
+
+## Implementation Date
+
+February 1, 2024
+
+## Deliverables
+
+### 1. JSON Schemas
+
+Located in `src/conversations/`:
+
+- **conversation.schema.json**: Defines the structure for conversation data including turns, metadata, and classification
+- **candidate.schema.json**: Defines the structure for emission candidates (GitHub issues, documentation, etc.)
+
+### 2. Core Pipeline Modules
+
+The pipeline follows this deterministic flow:
+
+```
+capture → redact → normalize → classify → candidates → gate → emit
+```
+
+**Modules** (all in `src/conversations/`):
+
+- `capture.ts`: Capture conversations from various sources
+- `redact.ts`: Deterministic PII redaction (email, phone, IP, SSN, credit cards)
+- `normalize.ts`: Content normalization (whitespace, code blocks)
+- `classify.ts`: Keyword-based classification (bug-report, feature-request, question, etc.)
+- `candidates.ts`: Generate emission candidates from classified conversations
+- `gate.ts`: Quality gates (minimum length, valid title, metadata, duplicates)
+
+### 3. Emitters
+
+Located in `src/conversations/emitters/`:
+
+- **fs.ts**: Filesystem emitter with dry-run support
+- **github.ts**: GitHub issue emitter with **HARD GATE** on `commit_intent=true`
+
+### 4. CLI Commands
+
+Command: `praxis conversations [subcommand]`
+
+Subcommands:
+- `capture`: Capture a conversation from input
+- `push`: Process through redact + normalize pipeline
+- `classify`: Classify conversation and generate candidate
+- `emit`: Emit candidate to fs or github (with gates)
+
+### 5. Tests & Fixtures
+
+- **Tests**: `src/__tests__/conversations.test.ts` (18 comprehensive tests)
+- **Fixtures**: `test/fixtures/conversations/` (3 test conversations)
+  - bug-report.json
+  - feature-request.json
+  - question.json
+
+All tests passing (18/18 for conversations, 404/408 total)
+
+### 6. Documentation
+
+- **README**: `src/conversations/README.md` (comprehensive guide)
+- Includes schema documentation, CLI usage, and programmatic API examples
+
+## Key Features
+
+1. **Deterministic-first**: No LLM required, all logic is rule-based
+2. **Hard-gated GitHub emitter**: Requires explicit `--commit-intent` flag
+3. **PII redaction**: Automatic removal of sensitive data
+4. **Quality gates**: 4 gates ensure quality before emission
+5. **Dry-run mode**: Test without side effects
+6. **Extensible**: Easy to add new emitters, classifiers, or gates
+
+## Usage Examples
+
+### CLI Usage
+
+```bash
+# Full pipeline
+praxis conversations push -i input.json -o processed.json
+praxis conversations classify -i processed.json -o candidate.json
+praxis conversations emit -i candidate.json -e fs --output-dir ./output
+
+# GitHub emission (requires --commit-intent)
+praxis conversations emit -i candidate.json -e github \
+  --owner myorg --repo myrepo --commit-intent
+```
+
+### Programmatic Usage
+
+```typescript
+import {
+  captureConversation,
+  redactConversation,
+  normalizeConversation,
+  classifyConversation,
+  generateCandidate,
+  applyGates,
+  emitToFS,
+} from '@plures/praxis/conversations';
+
+// Process conversation
+let conv = captureConversation({ turns: [...], metadata: {} });
+conv = redactConversation(conv);
+conv = normalizeConversation(conv);
+conv = classifyConversation(conv);
+
+// Generate and emit candidate
+const candidate = generateCandidate(conv);
+const gated = applyGates(candidate);
+if (gated.gateStatus?.passed) {
+  await emitToFS(gated, { outputDir: './output' });
+}
+```
+
+## Security
+
+- **CodeQL Scan**: 0 vulnerabilities found
+- **PII Redaction**: Implemented for emails, phones, IPs, SSNs, credit cards
+- **GitHub Gate**: Hard-gated to prevent accidental issue creation
+- **Input Validation**: All inputs validated before processing
+
+## Testing
+
+All tests passing:
+- Conversations subsystem: 18/18 tests
+- Full test suite: 404/408 tests (4 skipped)
+
+Run tests:
+```bash
+npm test src/__tests__/conversations.test.ts
+npm test  # Full suite
+```
+
+## Code Review
+
+Code review completed with all feedback addressed:
+- Documented intentionally broad PII patterns (prioritize safety)
+- Optimized label deduplication using Set (O(n) vs O(n²))
+- Added clarifying comments for pattern limitations
+
+## Files Modified/Created
+
+### New Files (19 total)
+
+**Core modules**:
+- src/conversations/candidate.schema.json
+- src/conversations/candidates.ts
+- src/conversations/capture.ts
+- src/conversations/classify.ts
+- src/conversations/conversation.schema.json
+- src/conversations/gate.ts
+- src/conversations/index.ts
+- src/conversations/normalize.ts
+- src/conversations/redact.ts
+- src/conversations/types.ts
+- src/conversations/README.md
+
+**Emitters**:
+- src/conversations/emitters/fs.ts
+- src/conversations/emitters/github.ts
+
+**CLI**:
+- src/cli/commands/conversations.ts
+
+**Tests & Fixtures**:
+- src/__tests__/conversations.test.ts
+- test/fixtures/conversations/bug-report.json
+- test/fixtures/conversations/feature-request.json
+- test/fixtures/conversations/question.json
+
+### Modified Files
+
+- src/cli/index.ts (added conversations commands)
+- .gitignore (added .demo/)
+
+## Compliance with Praxis Decision Ledger
+
+This implementation follows the Praxis Decision Ledger dogfooding guidelines:
+- Deterministic implementation (no LLM dependencies)
+- Comprehensive test coverage
+- Clear contracts and schemas
+- Documentation for all public APIs
+
+## Future Enhancements
+
+Potential improvements for future iterations:
+- Additional emitters (Slack, Discord, email)
+- More sophisticated classification rules
+- Duplicate detection against real GitHub issues
+- Custom PII patterns via configuration
+- Batch processing support
+
+## Conclusion
+
+The praxis-conversations subsystem has been successfully implemented with:
+- Complete deterministic pipeline
+- Hard-gated GitHub emitter
+- Comprehensive tests and documentation
+- Zero security vulnerabilities
+- All code review feedback addressed
+
+The subsystem is ready for use and follows all Praxis framework conventions.

package/docs/archive/1.x/DECISION_LEDGER_IMPLEMENTATION.md

@@ -0,0 +1,109 @@
+# Decision Ledger Reverse Engineering - Implementation Summary
+
+This document provides a comprehensive summary of the decision ledger reverse engineering implementation for the Praxis framework.
+
+## What Was Implemented
+
+### Core Components
+
+1. **Repository Scanner** (`src/decision-ledger/scanner.ts`)
+   - Scans codebases to discover existing rules and constraints
+   - Maps test files to rules by ID references
+   - Maps spec files (TLA+, markdown) to rules
+   - Infers contract information from code and comments
+   - Includes error handling with warnings collection
+   - Path validation and normalization
+
+2. **Reverse Contract Generator** (`src/decision-ledger/reverse-generator.ts`)
+   - Generates contracts from existing code
+   - Supports AI-powered generation (OpenAI, GitHub Copilot)
+   - Fallback to heuristic-based generation
+   - Confidence scoring system (normalized, capped at 0.9)
+   - Extracts examples from test files
+   - Generates default assumptions
+
+3. **CLI Command** (`src/cli/commands/reverse.ts`)
+   - `praxis reverse` command for reverse engineering
+   - Interactive mode with user prompts
+   - Batch processing with limit control
+   - Dry-run mode for previewing
+   - Multiple output formats (JSON, YAML)
+   - Logic ledger integration
+   - Unique filename generation with hashes
+   - Comprehensive progress reporting
+
+### Features
+
+#### Repository Scanning
+- **File pattern matching**: Discovers `defineRule()` and `defineConstraint()` patterns
+- **Test mapping**: Links test files to rules by searching for rule IDs
+- **Spec mapping**: Links specification files to rules
+- **Artifact tracking**: Builds index of tests and specs for validation
+- **Error handling**: Collects warnings for permission errors and scan issues
+- **Exclusion patterns**: Respects node_modules, dist, build directories
+
+#### Contract Generation
+- **Heuristic analysis**: Infers behavior from JSDoc, descriptions, code structure
+- **AI integration**: Placeholder hooks for OpenAI and GitHub Copilot
+- **Confidence scoring**: Normalized scoring based on available artifacts
+- **Example extraction**: Parses test descriptions into Given/When/Then format
+- **Assumption generation**: Creates default assumptions with confidence levels
+- **Reference tracking**: Links to test files and spec files
+
+#### Migration Support
+- **Backward compatible**: Existing Praxis code works without modification
+- **Incremental adoption**: Process rules one at a time or in batches
+- **Interactive review**: Prompt for each contract generation
+- **Dry-run mode**: Preview without writing files
+- **Multiple formats**: Output as JSON or YAML
+
+## Documentation
+
+1. **Reverse Engineering Guide** (`src/decision-ledger/REVERSE_ENGINEERING.md`)
+   - Comprehensive guide for migrating existing codebases
+   - Step-by-step migration workflow
+   - Examples of generated contracts
+   - Best practices and troubleshooting
+
+2. **Updated README** (`src/decision-ledger/README.md`)
+   - Added reverse engineering section
+   - CLI command documentation
+   - API reference updates
+
+## Testing
+
+All tests pass (378 passed, 4 skipped out of 382 total tests).
+
+- Scanner tests verify contract inference
+- Generator tests verify contract generation with various inputs
+- Confidence scoring tests ensure proper normalization
+- Build verification successful
+
+## Key Features
+
+✅ Repository scanning with pattern matching  
+✅ AI integration hooks (placeholder)  
+✅ Heuristic-based contract generation  
+✅ Interactive and batch modes  
+✅ Error handling with warnings  
+✅ Comprehensive documentation  
+✅ Full test coverage  
+✅ Code review feedback addressed  
+
+## Usage Example
+
+```bash
+# Scan and generate contracts
+praxis reverse --output ./contracts
+
+# Interactive mode
+praxis reverse --interactive
+
+# With AI (when implemented)
+praxis reverse --ai openai
+
+# Commit to ledger
+praxis reverse --ledger --author "team"
+```
+
+See [REVERSE_ENGINEERING.md](src/decision-ledger/REVERSE_ENGINEERING.md) for complete documentation.