@paths.design/caws-cli 10.1.0 → 11.0.0

package/dist/templates/OIDC_SETUP.md

@@ -1,300 +0,0 @@
-# OIDC Trusted Publisher Setup
-
-This guide helps you set up OIDC (OpenID Connect) trusted publisher for automated publishing to package registries.
-
-## Overview
-
-OIDC trusted publisher allows you to publish packages without storing long-lived tokens or passwords in your CI/CD environment. Instead, it uses short-lived tokens issued by the OIDC provider.
-
-## Supported Registries
-
-- **npm**: npm Registry
-- **PyPI**: Python Package Index
-- **Maven Central**: Java packages
-- **NuGet**: .NET packages
-
-## Setup Process
-
-### 1. Configure OIDC Provider
-
-Most CI/CD platforms (GitHub Actions, GitLab CI, etc.) provide built-in OIDC support.
-
-**GitHub Actions Example:**
-
-```yaml
-# .github/workflows/publish.yml
-name: Publish Package
-
-on:
-  release:
-    types: [published]
-
-jobs:
-  publish:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
-    steps:
-      - uses: actions/checkout@v4
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-      - name: Install dependencies
-        run: npm ci
-      - name: Build package
-        run: npm run build
-      - name: Publish to npm
-        run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
-
-### 2. Registry Configuration
-
-#### npm Registry
-
-1. **Create OIDC Integration**:
-
-   ```bash
-   # Using npm CLI
-   npm profile enable-2fa auth-and-writes
-   ```
-
-2. **Configure Trusted Publisher**:
-   - Go to npmjs.com → Account Settings → Access Tokens
-   - Create "Automation" token
-   - Configure OIDC integration
-
-3. **Repository Settings**:
-   ```json
-   // package.json
-   {
-     "publishConfig": {
-       "registry": "https://registry.npmjs.org/"
-     }
-   }
-   ```
-
-#### PyPI (Python)
-
-1. **Create API Token**:
-
-   ```bash
-   # Using twine
-   twine upload --config-file ~/.pypirc dist/*
-   ```
-
-2. **OIDC Configuration**:
-   ```yaml
-   # .github/workflows/publish.yml
-   - name: Publish to PyPI
-     uses: pypa/gh-action-pypi-publish@release/v1
-     with:
-       password: ${{ secrets.PYPI_API_TOKEN }}
-   ```
-
-### 3. Security Best Practices
-
-#### Token Management
-
-- ✅ **Use short-lived tokens** (1-6 hours)
-- ✅ **Scope tokens to specific repositories**
-- ✅ **Rotate tokens regularly**
-- ❌ **Never store long-lived tokens in code**
-- ❌ **Never commit tokens to version control**
-
-#### Environment Variables
-
-```bash
-# Good: Short-lived, scoped token
-NODE_AUTH_TOKEN=gho_shortlivedtoken123
-
-# Bad: Long-lived, broad token
-NPM_TOKEN=longlivedbroadtoken456
-```
-
-#### Repository Secrets
-
-Store sensitive tokens in repository secrets:
-
-**GitHub**: Settings → Secrets and variables → Actions
-**GitLab**: Settings → CI/CD → Variables
-**Azure DevOps**: Pipelines → Library → Variable groups
-
-### 4. Testing the Setup
-
-#### Local Testing
-
-```bash
-# Test with dry run
-npm publish --dry-run
-
-# Test with local registry
-npm publish --registry http://localhost:4873
-```
-
-#### CI/CD Testing
-
-```yaml
-# Add to your workflow for testing
-- name: Test publish (dry run)
-  run: npm publish --dry-run
-  env:
-    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-```
-
-### 5. Troubleshooting
-
-#### Common Issues
-
-**Token Expired**:
-
-```
-npm ERR! code E401
-npm ERR! Unable to authenticate, need: Basic
-```
-
-**Solution**: Check token expiration and refresh if needed.
-
-**Insufficient Permissions**:
-
-```
-npm ERR! code E403
-npm ERR! Forbidden
-```
-
-**Solution**: Verify token has publish permissions for the package.
-
-**OIDC Provider Issues**:
-
-```
-Error: Failed to get OIDC token
-```
-
-**Solution**: Check OIDC provider configuration and permissions.
-
-#### Debug Mode
-
-Enable debug logging:
-
-```bash
-# npm
-npm config set loglevel verbose
-
-# Python
-export TWINE_VERBOSE=1
-
-# Maven
-mvn deploy -X
-```
-
-### 6. Migration from Legacy Tokens
-
-If you're migrating from username/password or long-lived tokens:
-
-1. **Audit existing tokens**:
-
-   ```bash
-   # npm
-   npm profile get
-
-   # List all tokens
-   npm token list
-   ```
-
-2. **Revoke old tokens**:
-
-   ```bash
-   npm token delete <token-id>
-   ```
-
-3. **Update CI/CD workflows**:
-   - Replace `NPM_TOKEN` with `NODE_AUTH_TOKEN`
-   - Add OIDC permissions
-   - Test in staging environment
-
-### 7. Monitoring and Alerts
-
-Set up monitoring for:
-
-- **Publish failures**: Alert on failed deployments
-- **Token expiration**: Proactive token renewal
-- **Security events**: Unusual publish patterns
-- **Registry status**: External service health
-
-#### Example Monitoring
-
-```yaml
-# .github/workflows/monitor.yml
-name: Monitor Publishing
-
-on:
-  workflow_run:
-    workflows: ['Publish Package']
-    types: [completed]
-
-jobs:
-  monitor:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check publish status
-        if: ${{ github.event.workflow_run.conclusion == 'failure' }}
-        run: |
-          echo "Publish failed! Check logs."
-          # Send alert to Slack/Teams/etc.
-```
-
-## CAWS Integration
-
-For CAWS projects, OIDC setup integrates with:
-
-- **Provenance tracking**: Automatic attestation of published packages
-- **Security scanning**: Validation of published artifacts
-- **Quality gates**: Ensure packages meet standards before publish
-
-### CAWS-Specific Configuration
-
-```yaml
-# .caws/working-spec.yaml
-non_functional:
-  security:
-    - 'oidc-authentication'
-    - 'token-rotation'
-    - 'publish-attestation'
-```
-
-### Automated Provenance
-
-CAWS automatically generates provenance information:
-
-```bash
-# Generate SBOM and attestation
-caws attest --format=slsa
-
-# Validate before publish
-caws validate --security-scan
-```
-
-## Resources
-
-- [npm OIDC Documentation](https://docs.npmjs.com/about-access-tokens)
-- [GitHub Actions OIDC](https://docs.github.com/en/actions/deployment/security/hardening-your-deployments/about-security-hardening-with-openid-connect)
-- [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishing/)
-- [OIDC Specification](https://openid.net/connect/)
-
-## Support
-
-For issues with OIDC setup:
-
-1. Check the troubleshooting section above
-2. Review registry-specific documentation
-3. Open an issue in the CAWS repository
-4. Contact your organization's security team
-
----
-
-**Note**: This guide provides general OIDC setup instructions. Always follow your organization's specific security policies and procedures.
-

package/dist/templates/agents.md

@@ -1,145 +0,0 @@
-# AGENTS.md
-
-This project uses [CAWS](https://github.com/paths-design/caws) (Coding Agent Working Standard) for quality-assured AI-assisted development.
-
-## Build & Test
-
-```bash
-npm install              # Install dependencies
-npm test                 # Run tests
-npm run lint             # Lint code
-npm run typecheck        # Type check (if TypeScript)
-caws validate            # Validate the current CAWS spec
-```
-
-## Project Structure
-
-```
-.caws/
-  working-spec.yaml      # Compatibility mirror for legacy paths
-  specs/                 # Canonical feature specs
-  policy.yaml            # Quality policy overrides (optional)
-  waivers.yml            # Active waivers (optional)
-```
-
-## CAWS Workflow
-
-1. **Read the canonical spec**: Use `.caws/specs/<spec-id>.yaml` when feature specs exist
-2. **Validate**: Run `caws validate --spec-id <spec-id>` for feature work
-3. **Plan**: Run `caws iterate` for implementation guidance
-4. **Implement**: Write tests first, then implementation. Stay within scope boundaries.
-5. **Verify**: Run `caws evaluate` to check quality compliance
-6. **Commit**: Use conventional commits (`feat:`, `fix:`, `refactor:`, `docs:`, `chore:`)
-
-For a new feature in a multi-agent project:
-
-```bash
-caws specs create my-feature --type feature --title "My Feature"
-caws validate --spec-id my-feature
-```
-
-## Scope and Worktree Binding
-
-The scope guard enforces `scope.in` and `scope.out` from your spec. How it enforces depends on binding:
-
-- **Authoritative mode** (worktree bound to a spec): Only your spec's scope is checked. Other agents' specs cannot block you.
-- **Union mode** (no binding): ALL active specs are checked. Any `scope.out` from any spec can block you.
-
-```bash
-# See your effective scope and binding health
-caws scope show
-
-# Fix a broken binding
-caws worktree bind <spec-id>
-```
-
-**Recovery** (when blocked unexpectedly):
-1. Run `caws scope show` to check mode and binding health
-2. If union mode: `caws worktree bind <spec-id>`
-3. If authoritative but blocked: update your spec's `scope.in`
-4. Do NOT edit another spec's `scope.out` to unblock yourself
-
-## Key Rules
-
-1. **Stay in scope** -- only edit files listed in `scope.in`, never touch `scope.out`
-2. **Respect change budgets** -- stay within `max_files` and `max_loc` limits
-3. **No shadow files** -- edit in place, never create `*-enhanced.*`, `*-new.*`, `*-v2.*`, `*-final.*` copies
-4. **Tests first** -- write failing tests before implementation
-5. **Deterministic code** -- inject time, random, and UUID generators for testability
-6. **No fake implementations** -- no placeholder stubs, no `TODO` in committed code, no in-memory arrays pretending to be persistence, no hardcoded mock responses
-7. **Prove claims** -- never assert "production-ready", "complete", or "battle-tested" without passing all quality gates. Provide evidence (test results, coverage reports), not assertions.
-8. **No marketing language in docs** -- avoid "revolutionary", "cutting-edge", "state-of-the-art", "enterprise-grade" in documentation and comments
-9. **Ask first for risky changes** -- changes touching >10 files, >300 LOC, crossing package boundaries, or affecting security/infrastructure require discussion before implementation
-
-## Quality Gates
-
-Requirements are tiered based on the `risk_tier` in the active spec:
-
-| Gate | T1 (Critical) | T2 (Standard) | T3 (Low Risk) |
-|------|---------------|----------------|----------------|
-| Test coverage | 90%+ | 80%+ | 70%+ |
-| Mutation score | 70%+ | 50%+ | 30%+ |
-| Contracts | Required | Required | Optional |
-| Manual review | Required | Optional | Optional |
-
-## Code Style
-
-- Prefer `const` over `let`
-- Use guard clauses and early returns over deep nesting
-- Single responsibility: one reason to change per module
-- Depend on abstractions, not concretions
-- Extension points over editing internals (open/closed principle)
-- Max cyclomatic complexity per function: 10
-- Max nesting depth: 4
-- Max function length: 50 lines
-- Max file length: 1000 lines
-- Max parameters: 5
-- No emojis in production code or logs
-- Check if a server/process is already running before starting another
-
-### Naming
-
-Forbidden file name modifiers: `enhanced`, `unified`, `better`, `new`, `next`, `final`, `copy`, `revamp`, `improved`. Use in-place edits with merge-then-delete strategy for refactors.
-
-## Modes
-
-| Mode | Contracts | New Files | Key Artifacts |
-|------|-----------|-----------|---------------|
-| **feature** | Required first | Allowed in scope.in | Migration plan, feature flag, perf budget |
-| **refactor** | Must not change | Discouraged | Codemod script + semantic diff |
-| **fix** | Unchanged | Discouraged | Red test -> green; root cause note |
-| **doc** | N/A | Docs only | Updated README/usage snippets |
-| **chore** | N/A | Build/tools only | Version updates, dependency changes |
-
-## Waivers
-
-If you need to bypass a quality gate, create a waiver with justification:
-
-```bash
-caws waivers create --reason emergency_hotfix --gates coverage_threshold
-```
-
-Valid reasons: `emergency_hotfix`, `legacy_integration`, `experimental_feature`, `performance_critical`, `infrastructure_limitation`
-
-## Pre-Submit Checklist
-
-- [ ] Canonical spec exists and validates (`caws validate --spec-id <spec-id>` when applicable)
-- [ ] All tests pass (`npm test`)
-- [ ] Coverage meets tier requirements
-- [ ] Lints pass (`npm run lint`)
-- [ ] Types check (`npm run typecheck`)
-- [ ] No scope violations
-- [ ] Change budget not exceeded (`caws burnup --spec-id <spec-id>` shows budget consumption)
-- [ ] Acceptance criteria proven (`caws verify-acs --spec-id <spec-id>` checks evidence exists)
-- [ ] Conventional commit message
-
-### Optional: Self-Diagnosis with Sidecars
-
-If a gate blocks you, use sidecar commands to understand why before retrying:
-
-```bash
-caws sidecar gaps          # What's missing? Which gates are failing and why?
-caws sidecar drift         # Has implementation drifted from the spec intent?
-caws sidecar waiver-draft  # Generate a pre-filled waiver if the gap is acceptable
-caws sidecar provenance    # Summarize work history for merge readiness
-```

package/dist/templates/codemod/README.md

@@ -1 +0,0 @@
-# Codemod Scripts

package/dist/templates/codemod/test.js

@@ -1,93 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Template Codemod for CAWS Framework
- * Automated code transformations for refactoring
- * @author CAWS Framework
- */
-
-const tsMorph = require('ts-morph');
-
-function applyCodemod(dryRun = true) {
-  console.log('🔧 Applying codemod transformations...');
-
-  const project = new tsMorph.Project();
-
-  // Load all TypeScript source files
-  const sourceFiles = project.addSourceFilesAtPaths('src/**/*.ts');
-
-  if (sourceFiles.length === 0) {
-    console.log('⚠️  No TypeScript source files found in src/ directory');
-    return { filesProcessed: 0, changesApplied: 0 };
-  }
-
-  console.log(`📁 Processing ${sourceFiles.length} source files`);
-  let totalChanges = 0;
-
-  for (const sourceFile of sourceFiles) {
-    const filePath = sourceFile.getFilePath();
-    console.log(`Processing: ${filePath}`);
-
-    let fileChanges = 0;
-
-    // Example transformations - customize these for your specific needs:
-
-    // 1. Add JSDoc to exported functions without documentation
-    const exportedFunctions = sourceFile
-      .getFunctions()
-      .filter((func) => func.isExported && !func.getJsDocs().length);
-
-    for (const func of exportedFunctions) {
-      func.addJsDoc({
-        description: `Handles ${func.getName()} operations`,
-        tags: [
-          { tagName: 'param', text: 'options - Configuration options' },
-          { tagName: 'returns', text: 'Result of the operation' },
-        ],
-      });
-      fileChanges++;
-    }
-
-    // 2. Add type annotations to untyped parameters (example)
-    // const untypedParams = sourceFile.getDescendantsOfKind(tsMorph.SyntaxKind.Parameter)
-    //   .filter(param => !param.getTypeNode());
-    // Add your transformation logic here...
-
-    if (fileChanges > 0) {
-      console.log(`  ✅ Applied ${fileChanges} transformations`);
-      totalChanges += fileChanges;
-    }
-  }
-
-  console.log(`📊 Codemod complete: ${totalChanges} total transformations`);
-
-  if (!dryRun) {
-    console.log('💾 Saving changes...');
-    project.saveSync();
-    console.log('✅ All changes saved successfully');
-  } else {
-    console.log('🔍 Dry run - no files were modified');
-  }
-
-  return {
-    filesProcessed: sourceFiles.length,
-    changesApplied: totalChanges,
-  };
-}
-
-// CLI interface
-if (require.main === module) {
-  const args = process.argv.slice(2);
-  const dryRun = !args.includes('--apply');
-
-  try {
-    const result = applyCodemod(dryRun);
-    console.log('✅ Codemod execution completed');
-    process.exit(0);
-  } catch (error) {
-    console.error('❌ Codemod execution failed:', error.message);
-    process.exit(1);
-  }
-}
-
-module.exports = { applyCodemod };

package/dist/templates/docs/README.md

@@ -1,151 +0,0 @@
-# CAWS Project Documentation
-
-## Overview
-This project is built with the **Coding Agent Workflow System (CAWS)** - an engineering-grade framework that ensures quality, reliability, and maintainability in AI-assisted development.
-
-## Key Features
-- **Quality Gates**: Automated validation of scope, budget, and standards
-- **Comprehensive Testing**: Unit, contract, integration, and mutation testing
-- **Observability**: Structured logging, metrics, and tracing
-- **Rollback Ready**: Feature flags and migration support
-- **Provenance Tracking**: SBOM and SLSA attestation generation
-
-## Getting Started
-
-### 1. Project Setup
-The project is already scaffolded with CAWS. Review and customize:
-- `.caws/specs/<spec-id>.yaml` - Canonical feature specification and requirements
-- `.caws/working-spec.yaml` - Compatibility mirror for legacy paths
-- `.caws/policy.yaml` - Risk tier definitions
-- `.github/workflows/caws.yml` - CI/CD quality gates
-
-### 2. Development Workflow
-1. **Plan**: Update the active feature spec with requirements and scope
-2. **Implement**: Follow agent conduct rules and mode constraints
-3. **Verify**: Run tests and quality gates locally
-4. **Document**: Update documentation and generate provenance
-
-### 3. Quality Assurance
-- Run `npm run test` for all tests
-- Check trust score with CAWS tools
-- Validate against working specification
-- Ensure rollback capabilities
-
-## Architecture
-
-### Directory Structure
-```
-src/                    # Source code
-├── core/              # Core business logic
-├── api/               # API endpoints
-├── models/            # Data models
-└── utils/             # Utilities
-
-tests/                 # Test suites
-├── unit/             # Unit tests
-├── contract/         # Contract tests
-├── integration/      # Integration tests
-└── e2e/              # End-to-end tests
-
-apps/tools/caws/       # CAWS utilities
-└── prompt-lint.js    # Prompt validation
-└── attest.js         # SBOM/attestation generation
-```
-
-### Key Patterns
-- **Dependency Injection**: For testability and determinism
-- **Interface Segregation**: Clean boundaries and contracts
-- **Observability**: Structured logging and metrics
-- **Property Testing**: Edge cases and invariants
-
-## Development Guidelines
-
-### Agent Conduct Rules
-1. **Spec Adherence**: Stay within declared scope and mode
-2. **Determinism**: Inject time, UUID, and random dependencies
-3. **Comprehensive Testing**: Unit + property + integration tests
-4. **Observability**: Log, metric, and trace key operations
-5. **Rollback Ready**: Feature flags and migration support
-
-### Code Quality
-- **Type Safety**: Full TypeScript coverage
-- **Test Coverage**: 80%+ branch coverage, 50%+ mutation score
-- **Performance**: API p95 < 250ms, accessibility compliance
-- **Security**: Input validation, rate limiting, secret scanning
-
-## Deployment
-
-### CI/CD Pipeline
-The project includes automated quality gates:
-- Static analysis and security scanning
-- Unit and integration testing
-- Performance and accessibility validation
-- Provenance and attestation generation
-
-### Environment Setup
-1. Configure environment variables
-2. Set up monitoring and alerting
-3. Establish rollback procedures
-4. Document operational runbooks
-
-## Monitoring & Observability
-
-### Metrics
-- Request latency and throughput
-- Error rates and types
-- Resource utilization
-- Business metrics
-
-### Logging
-- Structured logs with correlation IDs
-- Error tracking and alerting
-- Performance monitoring
-- Security event logging
-
-### Tracing
-- Distributed request tracing
-- Performance profiling
-- Dependency analysis
-- Root cause identification
-
-## Troubleshooting
-
-### Common Issues
-1. **Trust Score Low**: Check test coverage and quality gates
-2. **Scope Violations**: Ensure changes align with the active spec
-3. **Budget Exceeded**: Review change size and complexity
-4. **Flaky Tests**: Use property testing and proper mocking
-
-### Support
-- Check `agents.md` for comprehensive documentation
-- Review CI/CD logs for quality gate failures
-- Use CAWS tools for validation and debugging
-- Follow agent conduct rules for collaboration
-
-## Contributing
-
-### Development Process
-1. Update the active feature specification
-2. Create comprehensive tests
-3. Implement with quality gates
-4. Generate provenance artifacts
-5. Document changes thoroughly
-
-### Code Review
-- Review against the active feature spec
-- Check trust score and quality gates
-- Validate observability and rollback
-- Ensure documentation completeness
-
-## Resources
-
-- **[CAWS Framework](agents.md)**: Complete system documentation
-- **[Canonical Specs](.caws/specs/)**: Project requirements
-- **[Quality Gates](.github/workflows/caws.yml)**: CI/CD pipeline
-- **[Tools](apps/tools/caws/)**: Development utilities
-
----
-
-**Maintainer**: @darianrosebrook
-**Framework**: CAWS v1.0
-**Updated**: $(date)