@paths.design/caws-cli 9.3.2 → 10.0.1

package/dist/sidecars/spec-drift.js

@@ -0,0 +1,151 @@
+/**
+ * @fileoverview Spec Drift Analysis Sidecar
+ * Compares implementation evidence (files_touched, AC results, gate results)
+ * against spec scope and acceptance criteria.
+ * @author @darianrosebrook
+ */
+
+const _minimatch = require('minimatch');
+const minimatch = typeof _minimatch === 'function'
+  ? _minimatch
+  : (_minimatch.minimatch || (() => { throw new Error('minimatch export not found — expected v3 default or v5+ named export'); }));
+const { createSidecarOutput, createNoStateOutput } = require('./schema');
+const { getRecurrence } = require('../gates/feedback');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a file path is within the spec's declared scope.
+ * A file is in scope if it matches at least one scope.in pattern
+ * and does not match any scope.out pattern.
+ * @param {string} file
+ * @param {string[]} scopeIn
+ * @param {string[]} scopeOut
+ * @returns {boolean}
+ */
+function isInScope(file, scopeIn, scopeOut) {
+  if (scopeIn.length === 0) return true; // No scope.in means everything is allowed
+  const matchesIn = scopeIn.some(pattern => minimatch(file, pattern));
+  if (!matchesIn) return false;
+  const matchesOut = scopeOut.some(pattern => minimatch(file, pattern));
+  return !matchesOut;
+}
+
+/**
+ * Build a set of file paths that are referenced by any acceptance criterion.
+ * This is a rough heuristic: ACs that have results with file references, or
+ * whose descriptions mention paths present in files_touched.
+ * @param {object[]} acResults - state.acceptance_criteria.results
+ * @param {string[]} filesTouched
+ * @returns {Set<string>}
+ */
+function filesWithACCoverage(acResults, filesTouched) {
+  const covered = new Set();
+  if (!acResults || !filesTouched) return covered;
+
+  for (const result of acResults) {
+    // If a result references files explicitly, mark them covered
+    if (result.files) {
+      result.files.forEach(f => covered.add(f));
+    }
+    // Heuristic: any file_touched whose basename appears in the AC description
+    // is considered loosely covered
+    if (result.description) {
+      for (const file of filesTouched) {
+        const basename = file.split('/').pop();
+        if (result.description.includes(basename)) {
+          covered.add(file);
+        }
+      }
+    }
+  }
+  return covered;
+}
+
+/**
+ * Gather gate corroboration: how many scope_boundary failures exist in history.
+ * @param {object|null} state
+ * @returns {{ scope_failures: number, last_failure: string|null }}
+ */
+function getGateCorroboration(state) {
+  const recurrence = getRecurrence('scope_boundary', state);
+  if (!recurrence) return { scope_failures: 0, last_failure: null };
+  return { scope_failures: recurrence.count, last_failure: recurrence.lastSeen };
+}
+
+// ---------------------------------------------------------------------------
+// Main analysis
+// ---------------------------------------------------------------------------
+
+/**
+ * Analyze spec drift by comparing implementation evidence against spec intent.
+ * Pure function -- no side effects, no writes.
+ * @param {object|null} state - Working state (from loadState)
+ * @param {object} spec - Resolved spec object
+ * @returns {object} Sidecar output envelope
+ */
+function analyzeSpecDrift(state, spec) {
+  if (!state) {
+    return createNoStateOutput('drift', spec.id);
+  }
+
+  const scopeIn = (spec.scope && spec.scope.in) || [];
+  const scopeOut = (spec.scope && spec.scope.out) || [];
+  const filesTouched = state.files_touched || [];
+  const acceptance = spec.acceptance || [];
+  const acResults = (state.acceptance_criteria && state.acceptance_criteria.results) || [];
+
+  // 1. Scope analysis -- find files outside declared scope
+  const outOfScopeFiles = filesTouched.filter(f => !isInScope(f, scopeIn, scopeOut));
+
+  // 2. Acceptance criteria cross-reference
+  const acResultMap = new Map();
+  for (const r of acResults) {
+    acResultMap.set(r.id, r);
+  }
+
+  const failingCriteria = [];
+  const missingEvidence = [];
+
+  for (const ac of acceptance) {
+    const result = acResultMap.get(ac.id);
+    if (!result || result.status === 'UNCHECKED') {
+      missingEvidence.push({ id: ac.id, description: ac.description || ac.text || '' });
+    } else if (result.status === 'FAIL') {
+      failingCriteria.push({ id: ac.id, description: ac.description || ac.text || '' });
+    }
+  }
+
+  // 3. Scope creep -- files with no AC coverage
+  const covered = filesWithACCoverage(acResults, filesTouched);
+  const scopeCreepFiles = filesTouched.filter(f => !covered.has(f));
+
+  // 4. Gate corroboration
+  const gateCorroboration = getGateCorroboration(state);
+
+  // 5. Drift detection
+  const driftDetected = outOfScopeFiles.length > 0 ||
+    failingCriteria.length > 0 ||
+    missingEvidence.length > 0;
+
+  // 6. Summary
+  const parts = [];
+  if (outOfScopeFiles.length > 0) parts.push(`${outOfScopeFiles.length} file(s) outside scope`);
+  if (failingCriteria.length > 0) parts.push(`${failingCriteria.length} AC failing`);
+  if (missingEvidence.length > 0) parts.push(`${missingEvidence.length} AC unchecked`);
+  const summary = parts.length > 0 ? parts.join(', ') : 'No drift detected';
+
+  return createSidecarOutput('drift', spec.id, {
+    drift_detected: driftDetected,
+    out_of_scope_files: outOfScopeFiles,
+    failing_criteria: failingCriteria,
+    missing_evidence: missingEvidence,
+    scope_creep_files: scopeCreepFiles,
+    gate_corroboration: gateCorroboration,
+    summary,
+  });
+}
+
+module.exports = { analyzeSpecDrift };

package/dist/sidecars/waiver-draft.js

@@ -0,0 +1,176 @@
+/**
+ * @fileoverview Waiver Drafting Assistance Sidecar
+ * Generates pre-filled waiver templates from gate failure context.
+ * Reduces boilerplate for the human reviewer.
+ * @author @darianrosebrook
+ */
+
+const yaml = require('js-yaml');
+const { getRecurrence, GATE_CATEGORIES } = require('../gates/feedback');
+const { createSidecarOutput, createNoStateOutput } = require('./schema');
+
+// ---------------------------------------------------------------------------
+// Category → reason mapping
+// ---------------------------------------------------------------------------
+
+const CATEGORY_REASON_MAP = {
+  scope: 'third_party_constraint',
+  policy: 'infrastructure_limitation',
+  quality: 'experimental_feature',
+  architectural: 'legacy_integration',
+};
+
+// ---------------------------------------------------------------------------
+// Impact level from recurrence count
+// ---------------------------------------------------------------------------
+
+function impactFromRecurrence(count) {
+  if (count <= 1) return 'low';
+  if (count <= 3) return 'medium';
+  return 'high';
+}
+
+// ---------------------------------------------------------------------------
+// Template generation
+// ---------------------------------------------------------------------------
+
+/**
+ * Pad a description to meet the 50-char minimum.
+ * @param {string} desc
+ * @returns {string}
+ */
+function padDescription(desc) {
+  if (desc.length >= 50) return desc;
+  return desc + ' '.repeat(1) + 'This waiver allows temporary bypass while the issue is addressed.';
+}
+
+/**
+ * Clamp a string to max length.
+ * @param {string} str
+ * @param {number} max
+ * @returns {string}
+ */
+function clamp(str, max) {
+  if (str.length <= max) return str;
+  return str.slice(0, max - 3) + '...';
+}
+
+/**
+ * Build a waiver template for one failing gate.
+ * @param {object} gate - Gate result object
+ * @param {object} spec - Spec object
+ * @param {object} state - Working state (for recurrence)
+ * @returns {object} Draft object with gate, category, recurrence, template, yaml
+ */
+function buildDraft(gate, spec, state) {
+  const gateName = gate.name;
+  const category = GATE_CATEGORIES[gateName] || 'quality';
+  const reason = CATEGORY_REASON_MAP[category] || 'other';
+
+  const recurrenceInfo = getRecurrence(gateName, state);
+  const recurrenceCount = recurrenceInfo ? recurrenceInfo.count : 0;
+  const impact = impactFromRecurrence(recurrenceCount);
+
+  const now = new Date();
+  const expiresAt = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
+
+  // Build description from gate messages
+  const specTitle = spec?.title || spec?.id || 'unknown';
+  let rawTitle = `Waive ${gateName} for ${specTitle}`;
+  // Clamp title to 10-200 chars, pad if too short
+  if (rawTitle.length < 10) {
+    rawTitle = rawTitle + ' — temporary bypass';
+  }
+  const title = clamp(rawTitle, 200);
+
+  // Build description from messages
+  const messageText = gate.messages && gate.messages.length > 0
+    ? gate.messages.join('. ')
+    : `Gate ${gateName} is failing`;
+  let description = `Gate ${gateName} is blocking: ${messageText}. This waiver allows temporary bypass while ${gateName} is addressed.`;
+  description = padDescription(description);
+  description = clamp(description, 1000);
+
+  const template = {
+    id: 'WV-XXXX',
+    title,
+    reason,
+    description,
+    gates: [gateName],
+    risk_assessment: {
+      impact_level: impact,
+      mitigation_plan: '[REQUIRED: Describe how you will address the underlying issue within the waiver period]',
+      review_required: impact === 'high' || impact === 'critical',
+    },
+    expires_at: expiresAt.toISOString(),
+    approved_by: '[REQUIRED]',
+    created_at: now.toISOString(),
+    metadata: { environment: 'development' },
+  };
+
+  const yamlStr = yaml.dump(template, { lineWidth: 120, noRefs: true });
+
+  return {
+    gate: gateName,
+    category,
+    recurrence: recurrenceCount,
+    template,
+    yaml: yamlStr,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate waiver draft templates from gate failures.
+ * @param {object|null} state - Working state
+ * @param {object} [spec] - Spec object
+ * @param {object} [options={}] - Options
+ * @param {string} [options.gateName] - Filter to a specific gate
+ * @returns {object} Sidecar envelope
+ */
+function draftWaiver(state, spec, options = {}) {
+  const specId = spec?.id || 'unknown';
+
+  if (!state) {
+    return createNoStateOutput('waiver-draft', specId);
+  }
+
+  if (!state.gates || !state.gates.results) {
+    return createSidecarOutput('waiver-draft', specId, {
+      drafts: [],
+      instructions: '',
+      summary: 'No gate results available',
+    });
+  }
+
+  // Find failing gates
+  let failingGates = state.gates.results.filter(g => g.status === 'fail');
+
+  if (options.gateName) {
+    failingGates = failingGates.filter(g => g.name === options.gateName);
+  }
+
+  if (failingGates.length === 0) {
+    return createSidecarOutput('waiver-draft', specId, {
+      drafts: [],
+      instructions: '',
+      summary: 'No failing gates found',
+    });
+  }
+
+  const drafts = failingGates.map(gate => buildDraft(gate, spec, state));
+
+  const gateNames = drafts.map(d => d.gate).join(', ');
+  const summary = `${drafts.length} waiver draft${drafts.length !== 1 ? 's' : ''} generated for ${gateNames}`;
+
+  return createSidecarOutput('waiver-draft', specId, {
+    drafts,
+    instructions: 'Review and fill [REQUIRED] fields, then run: caws waivers create --file <path>',
+    summary,
+  });
+}
+
+module.exports = { draftWaiver };

package/dist/templates/.caws/schemas/policy.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CAWS Policy",
+  "type": "object",
+  "required": ["version", "risk_tiers"],
+  "properties": {
+    "version": { "type": "integer", "const": 1 },
+    "risk_tiers": {
+      "type": "object",
+      "properties": {
+        "1": { "$ref": "#/$defs/tier" },
+        "2": { "$ref": "#/$defs/tier" },
+        "3": { "$ref": "#/$defs/tier" }
+      },
+      "required": ["1", "2", "3"]
+    },
+    "edit_rules": {
+      "type": "object",
+      "properties": {
+        "policy_and_code_same_pr": { "type": "boolean" },
+        "min_approvers_for_budget_raise": { "type": "integer", "minimum": 1 },
+        "require_signed_commits": { "type": "boolean" }
+      }
+    },
+    "gates": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "description": { "type": "string" },
+          "mode": { "type": "string", "enum": ["block", "warn", "skip"] },
+          "thresholds": { "type": "object" }
+        },
+        "required": ["enabled"]
+      }
+    }
+  },
+  "$defs": {
+    "tier": {
+      "type": "object",
+      "required": ["max_files", "max_loc"],
+      "properties": {
+        "max_files": { "type": "integer", "minimum": 1 },
+        "max_loc": { "type": "integer", "minimum": 1 },
+        "description": { "type": "string" }
+      }
+    }
+  }
+}

package/dist/templates/.caws/schemas/waivers.schema.json

@@ -1,30 +1,36 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "CAWS Waivers Configuration",
+  "title": "CAWS Waiver",
+  "description": "Individual waiver file created by caws waivers create",
   "type": "object",
-  "patternProperties": {
-    ".*": {
-      "type": "object",
-      "required": ["gate", "reason", "owner", "expiry"],
-      "properties": {
-        "gate": {
-          "type": "string",
-          "enum": ["coverage", "mutation", "contracts", "a11y", "perf", "security"]
-        },
-        "reason": { "type": "string", "minLength": 10 },
-        "owner": { "type": "string" },
-        "expiry": { "type": "string", "format": "date-time" },
-        "compensating_control": { "type": "string" },
-        "ticket_url": { "type": "string", "format": "uri" },
-        "approved_by": { "type": "string" },
-        "created_at": { "type": "string", "format": "date-time" },
-        "status": {
-          "type": "string",
-          "enum": ["active", "expired", "revoked"],
-          "default": "active"
-        }
-      }
-    }
+  "required": ["id", "title", "reason", "gates", "created_at", "expires_at", "approved_by", "status"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^WV-\\d{4}$" },
+    "title": { "type": "string", "minLength": 1 },
+    "reason": { "type": "string", "minLength": 10 },
+    "description": { "type": "string" },
+    "gates": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1,
+      "description": "Gate names this waiver applies to"
+    },
+    "created_at": { "type": "string" },
+    "expires_at": { "type": "string" },
+    "approved_by": { "type": "string" },
+    "impact_level": { "type": "string" },
+    "mitigation_plan": { "type": "string" },
+    "status": {
+      "type": "string",
+      "enum": ["active", "expired", "revoked"],
+      "default": "active"
+    },
+    "created_by_session": { "type": ["string", "null"] },
+    "compensating_control": { "type": "string" },
+    "ticket_url": { "type": "string", "format": "uri" },
+    "revoked_at": { "type": "string" },
+    "revoked_by": { "type": "string" },
+    "revocation_reason": { "type": "string" }
   },
   "additionalProperties": false
 }

package/dist/templates/.caws/schemas/working-spec.schema.json

@@ -18,8 +18,15 @@
   "properties": {
     "id": { "type": "string", "pattern": "^[A-Z]{2,6}-\\d{3,4}$" },
     "title": { "type": "string", "minLength": 10, "maxLength": 200 },
+    "type": { "type": "string", "enum": ["feature", "fix", "refactor", "chore", "docs"] },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "active", "in_progress", "completed", "closed", "archived"]
+    },
+    "created_at": { "type": "string" },
+    "updated_at": { "type": "string" },
     "risk_tier": { "type": ["integer", "string"], "enum": [1, 2, 3, "1", "2", "3"] },
-    "mode": { "type": "string", "enum": ["feature", "refactor", "fix", "doc", "chore"] },
+    "mode": { "type": "string", "enum": ["feature", "refactor", "fix", "doc", "docs", "chore", "development"] },
     "waiver_ids": {
       "type": "array",
       "items": { "type": "string", "pattern": "^WV-\\d{4}$" },
@@ -45,7 +52,7 @@
     "invariants": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
     "acceptance": {
       "type": "array",
-      "minItems": 1,
+      "minItems": 0,
       "items": {
         "type": "object",
         "required": ["id", "given", "when", "then"],
@@ -57,6 +64,35 @@
         }
       }
     },
+    "acceptance_criteria": {
+      "type": "array",
+      "minItems": 0,
+      "items": {
+        "type": "object",
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "string" },
+          "description": { "type": "string" },
+          "completed": { "type": "boolean" },
+          "test": { "type": "string" },
+          "test_command": { "type": "string" },
+          "test_nodeids": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "evidence": {
+            "oneOf": [
+              { "type": "string" },
+              {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            ]
+          }
+        },
+        "additionalProperties": true
+      }
+    },
     "non_functional": {
       "type": "object",
       "properties": {
@@ -75,13 +111,14 @@
     },
     "contracts": {
       "type": "array",
-      "minItems": 1,
       "items": {
         "type": "object",
         "required": ["type", "path"],
         "properties": {
-          "type": { "type": "string", "enum": ["openapi", "graphql", "proto", "pact"] },
-          "path": { "type": "string" }
+          "type": { "type": "string", "enum": ["openapi", "graphql", "proto", "pact", "project_setup"] },
+          "path": { "type": "string" },
+          "description": { "type": "string" },
+          "version": { "type": "string" }
         }
       }
     },
@@ -95,9 +132,15 @@
     },
     "migrations": { "type": "array", "items": { "type": "string" } },
     "rollback": { "type": "array", "items": { "type": "string" } },
-    "experiment_mode": {
-      "type": "boolean",
-      "description": "Enables experimental mode with reduced requirements"
+    "experimental_mode": {
+      "type": "object",
+      "description": "Enables experimental mode with reduced requirements",
+      "required": ["enabled", "rationale", "expires_at"],
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "rationale": { "type": "string" },
+        "expires_at": { "type": "string" }
+      }
     },
     "timeboxed_hours": {
       "type": "integer",

package/dist/templates/.caws/schemas/worktrees.schema.json

@@ -21,11 +21,13 @@
           "baseBranch": { "type": "string" },
           "scope": { "type": ["string", "null"] },
           "specId": { "type": ["string", "null"] },
+          "owner": { "type": ["string", "null"], "description": "CLAUDE_SESSION_ID of the creating agent" },
           "createdAt": { "type": "string", "format": "date-time" },
           "destroyedAt": { "type": "string", "format": "date-time" },
+          "autoRegistered": { "type": "boolean" },
           "status": {
             "type": "string",
-            "enum": ["active", "orphaned", "missing", "destroyed"]
+            "enum": ["fresh", "active", "merged", "orphaned", "missing", "stale-merged", "destroyed"]
           }
         },
         "additionalProperties": false

package/dist/templates/.caws/templates/working-spec.template.yml

@@ -1,6 +1,10 @@
 id: '{{FEATURE_ID}}'
 title: '{{FEATURE_TITLE}}'
-risk_tier: { { TIER } }
+risk_tier: {{TIER}}
+mode: feature
+blast_radius:
+  modules: []
+operational_rollback_slo: "30m"
 scope:
   in:
     - '{{SCOPE_ITEM_1}}'
@@ -37,8 +41,8 @@ non_functional:
   a11y:
     - '{{ACCESSIBILITY_REQUIREMENT}}'
   perf:
-    api_p95_ms: { { PERF_BUDGET } }
-    lcp_ms: { { LCP_BUDGET } }
+    api_p95_ms: {{PERF_BUDGET}}
+    lcp_ms: {{LCP_BUDGET}}
   security:
     - '{{SECURITY_REQUIREMENT}}'
 contracts: