@paths.design/caws-cli 10.2.0 → 11.1.0

package/templates/COMMIT_CONVENTIONS.md

@@ -1,86 +0,0 @@
-# Commit Message Conventions
-
-This repository uses [Conventional Commits](https://conventionalcommits.org/) for automated versioning and changelog generation.
-
-## Format
-
-```
-<type>[optional scope]: <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-## Types
-
-- **feat**: A new feature
-- **fix**: A bug fix
-- **docs**: Documentation only changes
-- **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
-- **refactor**: A code change that neither fixes a bug nor adds a feature
-- **perf**: A code change that improves performance
-- **test**: Adding missing tests or correcting existing tests
-- **build**: Changes that affect the build system or external dependencies
-- **ci**: Changes to our CI configuration files and scripts
-- **chore**: Other changes that don't modify src or test files
-
-## Examples
-
-### Feature
-```
-feat: add user authentication system
-```
-
-### Bug Fix
-```
-fix: resolve memory leak in data processing
-```
-
-### Documentation
-```
-docs: update API documentation for new endpoints
-```
-
-### Refactoring
-```
-refactor: extract user validation logic into separate module
-```
-
-### Breaking Change
-```
-feat!: change API response format for user data
-
-BREAKING CHANGE: The user object now returns additional fields and the format has changed
-```
-
-## Scope
-
-The scope should be the name of the package or module affected by the change:
-
-```
-feat(auth): add OAuth2 authentication
-fix(api): resolve endpoint timeout issue
-docs(cli): update installation instructions
-```
-
-## Automated Publishing
-
-Commits following these conventions will automatically:
-
-1. **Trigger releases** when pushed to `main`
-2. **Generate changelogs** based on commit messages
-3. **Bump versions** according to semantic versioning:
-   - `fix:` → patch release (1.0.0 → 1.0.1)
-   - `feat:` → minor release (1.0.0 → 1.1.0)
-   - `feat!:` → major release (1.0.0 → 2.0.0)
-
-## CI/CD Integration
-
-The automated release process includes:
-- ✅ Linting and testing
-- ✅ Package building
-- ✅ NPM publishing with OIDC authentication
-- ✅ Changelog generation
-- ✅ Git tag creation
-- ✅ Release notes generation

package/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/templates/agents.md

@@ -1,171 +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
-
-## Multi-Agent Claims
-
-Each session is registered in `.caws/agents.json` automatically. Worktree session ownership is recorded in `.caws/worktrees.json:owner` as a session id. `caws worktree bind`, `merge`, and `claim` will refuse to mutate a worktree owned by a different session id without `--takeover`.
-
-```bash
-# See registered agents (composite <sessionId>:<platform> format)
-caws agents list
-
-# Inspect a worktree's claim — read-only by default
-caws worktree claim <name>
-
-# Take over a foreign claim (writes prior_owners audit)
-caws worktree claim <name> --takeover
-```
-
-When a refusal fires, the warning includes the claimer's session id, heartbeat age, and a pointer to any `tmp/<sessionId>/` session-log directory — read that log for context before deciding to take over. A stale heartbeat does NOT mean the prior session is dead; it may be paused.
-
-## Spec Lifecycle: Archive
-
-```bash
-# Move a closed spec to the canonical archive
-caws specs archive <spec-id>
-```
-
-The `.caws/specs/.archive/` directory is filesystem-authoritative — `caws specs list` reports any file under it as `archived` regardless of YAML status. `caws specs create` refuses ids that collide with archived files unless `--force` is supplied (which removes the archived copy and writes a fresh draft).
-
-## 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/templates/codemod/README.md

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

package/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 };