@paths.design/caws-cli 9.3.2 → 10.1.0

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,112 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "version",
+    "risk_tiers",
+    "edit_rules"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "enum": [
+        1
+      ],
+      "description": "Policy schema version"
+    },
+    "risk_tiers": {
+      "type": "object",
+      "patternProperties": {
+        "^[1-3]$": {
+          "type": "object",
+          "required": [
+            "max_files",
+            "max_loc"
+          ],
+          "properties": {
+            "max_files": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum files allowed for this risk tier"
+            },
+            "max_loc": {
+              "type": "integer",
+              "minimum": 1,
+              "description": "Maximum lines of code allowed for this risk tier"
+            },
+            "description": {
+              "type": "string",
+              "description": "Human-readable description of the tier"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false,
+      "description": "Risk tier definitions with budget limits"
+    },
+    "edit_rules": {
+      "type": "object",
+      "required": [
+        "policy_and_code_same_pr",
+        "min_approvers_for_budget_raise"
+      ],
+      "properties": {
+        "policy_and_code_same_pr": {
+          "type": "boolean",
+          "description": "Whether policy and code changes can be in the same PR"
+        },
+        "min_approvers_for_budget_raise": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Minimum approvers required for budget increases"
+        },
+        "require_signed_commits": {
+          "type": "boolean",
+          "description": "Whether signed commits are required for policy changes"
+        }
+      },
+      "additionalProperties": false,
+      "description": "Rules governing policy file edits"
+    },
+    "gates": {
+      "type": "object",
+      "patternProperties": {
+        "^.*$": {
+          "type": "object",
+          "required": [
+            "enabled"
+          ],
+          "properties": {
+            "enabled": {
+              "type": "boolean",
+              "description": "Whether this gate is active"
+            },
+            "mode": {
+              "type": "string",
+              "enum": [
+                "warn",
+                "block",
+                "skip"
+              ],
+              "description": "How the gate reports failures: warn, block, or skip entirely"
+            },
+            "description": {
+              "type": "string",
+              "description": "Human-readable description of the gate"
+            },
+            "thresholds": {
+              "type": "object",
+              "description": "Gate-specific thresholds (e.g. warning/critical limits)"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false,
+      "description": "Quality gate configurations"
+    }
+  },
+  "additionalProperties": false,
+  "title": "CAWS Policy"
+}

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

@@ -1,14 +1,14 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "title": "CAWS Lite Scope Configuration",
-  "description": "Scope configuration for CAWS lite mode — guardrails without YAML specs",
+  "description": "Scope configuration for CAWS lite mode — guardrails without YAML specs. This schema governs the standalone .caws/scope.json file ONLY; inline scope: blocks inside working-spec.yaml or feature specs are governed by the working-spec schema's scope sub-schema and do NOT invoke this schema. See CAWSFIX-11.",
   "type": "object",
-  "required": ["version", "allowedDirectories"],
+  "required": ["allowedDirectories"],
   "properties": {
     "version": {
       "type": "integer",
       "const": 1,
-      "description": "Schema version"
+      "description": "Schema version. Optional for back-compat with scope.json files that predate versioning; the runtime (src/config/lite-scope.js) defaults to 1 when missing. If present, must be exactly 1. CAWSFIX-11 lifted `version` from the required list because no code path enforces a version mismatch — only the schema did, producing spurious warnings for pre-versioning scope.json files."
     },
     "allowedDirectories": {
       "type": "array",

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

@@ -1,29 +1,105 @@
 {
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "title": "CAWS Waivers Configuration",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "CAWS Waiver",
+  "description": "Individual waiver file created by caws waivers create",
   "type": "object",
-  "patternProperties": {
-    ".*": {
+  "required": ["id", "applies_to", "gates", "delta", "reason_code", "expires_at", "risk_owner", "approvers", "status"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^WV-\\d{4}$",
+      "description": "Waiver ID in format WV-XXXX"
+    },
+    "applies_to": {
+      "type": "string",
+      "description": "Spec ID or PR number this waiver applies to"
+    },
+    "gates": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["budget_limit", "spec_completeness", "contract_compliance", "coverage_threshold", "mutation_threshold", "security_scan", "accessibility_check", "performance_budget", "scope_boundary"]
+      },
+      "minItems": 1,
+      "description": "Quality gates to waive"
+    },
+    "delta": {
       "type": "object",
-      "required": ["gate", "reason", "owner", "expiry"],
+      "description": "Additive budget deltas (only positive values allowed)",
       "properties": {
-        "gate": {
-          "type": "string",
-          "enum": ["coverage", "mutation", "contracts", "a11y", "perf", "security"]
+        "max_files": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Additional files allowed"
         },
-        "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"
+        "max_loc": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Additional lines of code allowed"
         }
-      }
+      },
+      "additionalProperties": false
+    },
+    "reason_code": {
+      "type": "string",
+      "enum": ["emergency_hotfix", "legacy_integration", "experimental_feature", "third_party_constraint", "performance_critical", "security_patch", "infrastructure_limitation", "architectural_refactor", "other"],
+      "description": "Controlled vocabulary for waiver reasons"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 50,
+      "maxLength": 1000,
+      "description": "Detailed explanation of why waiver is needed"
+    },
+    "mitigation": {
+      "type": "string",
+      "minLength": 50,
+      "description": "Plan to address the underlying issue"
+    },
+    "expires_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 datetime when waiver expires"
+    },
+    "risk_owner": {
+      "type": "string",
+      "description": "Person/entity responsible for managing this risk"
+    },
+    "approvers": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["handle"],
+        "properties": {
+          "handle": {
+            "type": "string",
+            "description": "GitHub handle or email of approver"
+          },
+          "approved_at": {
+            "type": "string",
+            "format": "date-time",
+            "description": "When this approval was given"
+          }
+        },
+        "additionalProperties": false
+      },
+      "minItems": 1,
+      "description": "List of people who approved this waiver"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["proposed", "active", "expired", "revoked"],
+      "description": "Current status of the waiver"
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "related_pr": { "type": "string" },
+        "related_issue": { "type": "string" },
+        "environment": { "type": "string", "enum": ["development", "staging", "production"] },
+        "urgency": { "type": "string", "enum": ["low", "normal", "high", "critical"] }
+      },
+      "additionalProperties": false
     }
   },
   "additionalProperties": false