@paths.design/caws-cli 11.1.1 → 11.1.3

package/README.md

@@ -1,21 +1,22 @@
 # @paths.design/caws-cli
 
-**CAWS CLI v11.0.0 — the governed core for the Coding Agent Working Standard.**
+**CAWS CLI v11.1 — the governed core plus lifecycle for the Coding Agent
+Working Standard.**
 
 CAWS (Coding Agent Working Standard) gives coding agents a deterministic
 substrate for project state, scope, claims, gates, waivers, and audit
-evidence. v11.0.0 is a ground-up rewrite around a pure kernel, an I/O
+evidence. v11 is a ground-up rewrite around a pure kernel, an I/O
 store, and a thin shell. It replaces v10.x.
 
 ## What v11 ships
 
-Exactly eight command groups. Nothing else.
+### Governed core (v11.0)
 
 | Command | What it does |
 |---|---|
 | `caws init` | Bootstrap the canonical `.caws/` project state. Idempotent. Refuses to overwrite legacy single-spec layout. |
 | `caws doctor` | Drift detection over `.caws/` state. Exits 0 (clean) / 1 (findings or load errors) / 2 (composition failure). |
-| `caws status` | Read-only dashboard: project, current context, claim, doctor findings. Always exits 0; never mutates `.caws/`. |
+| `caws status` | Read-only dashboard: project, current context, claim, doctor findings. Always exits 0; never mutates governance state. |
 | `caws scope show <path>` | Explain the scope decision for `<path>`. Always exits 0. |
 | `caws scope check <path>` | Enforce the scope decision for `<path>`. Exits 0 on admit, 1 on refuse. |
 | `caws claim [--takeover]` | Surface or take ownership of the current worktree. Writes a `prior_owners` audit on takeover. |
@@ -23,35 +24,39 @@ Exactly eight command groups. Nothing else.
 | `caws evidence record --type <kind> --spec <id> --data <json>` | Append a typed evidence event (`test`/`gate`/`ac`) to `.caws/events.jsonl`. |
 | `caws waiver create/list/show/revoke` | Manage waiver records that filter matching gate violations. Singular surface — no plural alias. |
 
+### Lifecycle (v11.1)
+
+| Command | What it does |
+|---|---|
+| `caws worktree create/list/bind/destroy/merge` | Worktree lifecycle on the vNext substrate. Canonical path for parallel agent work. |
+| `caws specs` | vNext spec lifecycle. |
+
 Run `caws <group> --help` for full options.
 
-## Posture: what v11 does NOT ship
-
-v11.0.0 is the **governed core**. It is not a complete lifecycle CLI.
-The following commands existed in v10.2.x and are **removed** in v11:
-
-- `caws scaffold` — installed legacy templates and git hooks.
-- `caws validate`, `caws verify-acs`, `caws evaluate`, `caws iterate`,
-  `caws diagnose`, `caws burnup` — used legacy spec resolution
-  (`working-spec.yaml` fallback) and a parallel event-log writer.
-- `caws specs`, `caws worktree`, `caws archive`, `caws parallel` —
-  spec/worktree lifecycle (returns in v11.1).
-- `caws provenance`, `caws hooks` — superseded by `.caws/events.jsonl`
-  and `caws gates run`. Generated git hooks called the removed
-  commands.
-- `caws sidecar`, `caws mode`, `caws tutorial`, `caws plan`,
-  `caws agents`, `caws session`, `caws templates`, `caws workflow`,
-  `caws quality-monitor`, `caws tool`, `caws test-analysis` —
-  peripherals not part of the governed core under A1.
-
-If your project depends on the legacy spec or worktree lifecycle
-commands, **pin to `caws-cli@^10.2.x` until v11.1 ships** vNext
-lifecycle commands. The two CLIs cannot coexist on the same project —
-they write to overlapping state.
+## Posture
+
+v11 is structured as kernel + store + shell. The kernel has no `fs`,
+`path`, or clock access; the store owns all I/O and the hash-chained
+event log; the shell composes them into commands.
+
+Commands that existed in v10.2.x and were **removed in v11.0** (no
+replacement is planned in any current milestone): `scaffold`, `validate`,
+`verify-acs`, `evaluate`, `iterate`, `diagnose`, `burnup`, `archive`,
+`provenance` (superseded by `events.jsonl`), `sidecar`, `mode`,
+`tutorial`, `plan`, `templates`, `workflow`, `quality-monitor`, `tool`,
+`test-analysis`, legacy `hooks` install (users wire their own hooks
+against `caws gates run`).
+
+Currently absent from v11.1 and **planned for v11.2** (multi-agent
+authority and observability): `caws agents list/show`, `caws claim
+--spec <id>` (bridge claims), `caws worktree prune/repair/reconcile`.
+
+Explicitly deferred to v11.3+: `caws session` and `caws parallel`. The
+`caws worktree create` loop pattern replaces `parallel` for multi-agent
+setup today.
 
 See `docs/architecture/caws-vnext-command-surface.md` in the repo for
-the complete cutover doctrine, removal table, and architectural
-invariants.
+the complete doctrine, command surface, and architectural invariants.
 
 ## Installation
 

package/dist/config/index.js

@@ -49,8 +49,11 @@ function initializeGlobalSetup() {
 function loadProvenanceTools() {
   if (provenanceTools) return provenanceTools; // Already loaded
 
-  // Provenance tools are now handled by CLI command (caws provenance)
-  // Legacy tool loading removed - use CLI instead
+  // v10 had a `caws provenance` command that loaded these tools. That
+  // command was removed in v11.0.0; the hash-chained .caws/events.jsonl
+  // is now the canonical audit surface (write via the v11 events-store
+  // or `caws evidence record`). This loader remains for legacy installs
+  // that still drop a local provenance.js into the search paths below.
   // Try multiple possible locations for provenance tools (legacy support)
   const possiblePaths = [
     // 1. New location (if someone manually adds it)

package/dist/error-handler.js

@@ -134,17 +134,30 @@ function safeSync(operation, context = '', includeTiming = false) {
 /**
  * Command-specific error suggestions
  */
+// v11 command surface. Mirrors docs/architecture/caws-vnext-command-surface.md
+// §2 — the eight v11.0 governed-core groups plus `specs` and `worktree`
+// restored in v11.1. When v11.2 lands `agents` and bridge claims, extend
+// this list in the same commit as the doctrine update.
+const V11_COMMANDS = [
+  'init',
+  'doctor',
+  'status',
+  'scope',
+  'claim',
+  'gates',
+  'evidence',
+  'waiver',
+  'specs',
+  'worktree',
+];
+
 const COMMAND_SUGGESTIONS = {
   'unknown option': (option, command) => {
     const suggestions = [];
 
-    // Common typos and alternatives
     const optionMap = {
-      '--suggestions': 'Validation includes suggestions by default. Try: caws validate',
-      '--suggest': 'Validation includes suggestions by default. Try: caws validate',
       '--help': 'Try: caws --help or caws <command> --help',
-      '--json': 'For JSON output, try: caws provenance show --format=json',
-      '--dashboard': 'Try: caws provenance show --format=dashboard',
+      '--json': 'v11 commands accept --json for machine-readable output where supported',
     };
 
     if (optionMap[option]) {
@@ -157,60 +170,45 @@ const COMMAND_SUGGESTIONS = {
   },
 
   'unknown command': (command) => {
-    const validCommands = [
-      'init',
-      'validate',
-      'scaffold',
-      'status',
-      'diagnose',
-      'evaluate',
-      'iterate',
-      'waivers',
-      'templates',
-      'provenance',
-      'hooks',
-      'workflow',
-      'quality-monitor',
-      'test-analysis',
-    ];
-    const similar = findSimilarCommand(command, validCommands);
+    const similar = findSimilarCommand(command, V11_COMMANDS);
 
     const suggestions = [];
     if (similar) {
       suggestions.push(`Did you mean: caws ${similar}?`);
     }
 
-    // Suggest category based on what user might be trying to do
-    if (command.includes('setup') || command.includes('start') || command.includes('create')) {
+    // Suggest category based on what the user might be trying to do.
+    // Each branch points only at the v11 surface — no removed-command leakage.
+    if (command.includes('setup') || command.includes('start')) {
       suggestions.push('For project setup: caws init');
+    } else if (command.includes('new') || command.includes('create')) {
+      suggestions.push('For a new spec: caws specs create <id>');
+      suggestions.push('For a new worktree: caws worktree create <name> --spec <id>');
     } else if (
       command.includes('check') ||
       command.includes('verify') ||
-      command.includes('test')
+      command.includes('valid')
     ) {
-      suggestions.push('For validation: caws validate');
+      suggestions.push('For drift detection: caws doctor');
+      suggestions.push('For policy and quality gates: caws gates run --spec <id>');
+      suggestions.push('For path scope: caws scope check <path>');
     } else if (command.includes('list') || command.includes('show') || command.includes('get')) {
-      suggestions.push('For status: caws status');
+      suggestions.push('For project status: caws status');
+      suggestions.push('For specs: caws specs list / caws specs show <id>');
+      suggestions.push('For worktrees: caws worktree list');
+    } else if (command.includes('evidence') || command.includes('record')) {
+      suggestions.push('To record test/gate/ac evidence: caws evidence record --type <kind> --spec <id> --data <json>');
     }
 
-    suggestions.push(
-      'Available commands: init, validate, scaffold, status, diagnose, evaluate, iterate, waivers, templates, provenance, hooks, workflow, quality-monitor'
-    );
+    suggestions.push(`Available v11 commands: ${V11_COMMANDS.join(', ')}`);
     suggestions.push('Try: caws --help for full command list with descriptions');
 
     return suggestions;
   },
 
-  'template not found': () => [
-    'Templates are bundled with CAWS CLI',
-    'Try: caws scaffold (should work automatically)',
-    'If issue persists: npm i -g @paths.design/caws-cli@latest',
-  ],
-
   'not a caws project': () => [
-    'Initialize CAWS first: caws init .',
-    'Or create new project: caws init <project-name>',
-    'Check for .caws/working-spec.yaml file',
+    'Initialize CAWS first: caws init',
+    'Verify .caws/ exists in the current directory',
   ],
 };
 
@@ -309,15 +307,15 @@ function getRecoverySuggestions(error, category, context = {}) {
       break;
 
     case ERROR_CATEGORIES.VALIDATION:
-      suggestions.push('Run: caws validate for detailed validation help');
-      suggestions.push('Check your working spec format against the schema');
-      suggestions.push('See: docs/api/schema.md for specification details');
+      suggestions.push('Run: caws doctor for spec and policy drift detection');
+      suggestions.push('Run: caws gates run --spec <id> for policy and quality gates');
+      suggestions.push('Check .caws/specs/<id>.yaml against the spec schema in packages/caws-kernel');
       break;
 
     case ERROR_CATEGORIES.CONFIGURATION:
-      suggestions.push('Run: caws init --interactive to reconfigure');
-      suggestions.push('Check your .caws directory and configuration files');
-      suggestions.push('Try: caws diagnose to identify configuration issues');
+      suggestions.push('Run: caws init to bootstrap canonical .caws/ state (idempotent)');
+      suggestions.push('Run: caws doctor to surface configuration drift');
+      suggestions.push('Inspect .caws/ contents directly to confirm expected layout');
       break;
 
     case ERROR_CATEGORIES.NETWORK:
@@ -352,12 +350,20 @@ function getDocumentationLink(category, context = {}) {
   };
 
   if (context.command) {
+    // v11 doc anchors. Generic fallback to the architecture doctrine if a
+    // specific command page is not yet authored.
+    const doctrine = `${baseUrl}/docs/architecture/caws-vnext-command-surface.md`;
     const commandLinks = {
-      init: `${baseUrl}/docs/agents/tutorial.md#initialization`,
-      validate: `${baseUrl}/docs/api/cli.md#validate`,
-      scaffold: `${baseUrl}/docs/api/cli.md#scaffold`,
-      provenance: `${baseUrl}/docs/api/cli.md#provenance`,
-      hooks: `${baseUrl}/docs/guides/hooks-and-agent-workflows.md`,
+      init: doctrine,
+      doctor: doctrine,
+      status: doctrine,
+      scope: doctrine,
+      claim: doctrine,
+      gates: doctrine,
+      evidence: doctrine,
+      waiver: doctrine,
+      specs: doctrine,
+      worktree: doctrine,
     };
 
     if (commandLinks[context.command]) {
@@ -522,29 +528,29 @@ const TROUBLESHOOTING_GUIDES = {
     ],
   },
 
-  'working-spec-validation': {
-    title: 'Working Spec Validation Errors',
+  'spec-validation': {
+    title: 'Spec Validation Errors',
     symptoms: [
-      'Working spec fails validation',
-      'Schema errors in .caws/working-spec.yaml',
-      'Invalid risk tier or scope configuration',
+      'A spec under .caws/specs/<id>.yaml fails to load',
+      'doctor reports spec.schema errors',
+      'Invalid risk tier, scope, or acceptance criteria',
     ],
     rootCauses: [
       'Invalid YAML syntax',
       'Missing required fields',
       'Incorrect schema structure',
-      'Invalid scope paths',
+      'Invalid scope paths (e.g., globs in scope.out)',
     ],
     solutions: [
-      'Run validation with suggestions: caws validate --suggestions',
-      'Auto-fix safe issues: caws validate --auto-fix',
-      'Check schema documentation',
-      'Use caws init to generate valid spec',
+      'Run: caws doctor — drift detection over .caws/ state',
+      'Inspect the failing spec at .caws/specs/<id>.yaml directly',
+      'Compare against existing specs in .caws/specs/ for shape',
+      'See packages/caws-kernel for the canonical spec schema',
     ],
     commands: [
-      'caws validate --suggestions',
-      'caws validate --auto-fix',
-      'caws init --interactive',
+      'caws doctor',
+      'caws specs show <id>',
+      'caws specs list',
     ],
   },
 
@@ -570,7 +576,7 @@ const TROUBLESHOOTING_GUIDES = {
     commands: [
       'cat package.json | grep workspaces',
       'find packages -name package.json',
-      'caws diagnose',
+      'caws doctor',
       'caws status',
     ],
   },
@@ -607,8 +613,14 @@ function suggestTroubleshootingGuide(errorMessage) {
   if (lowerMessage.includes('mutation') && lowerMessage.includes('not found')) {
     return 'mutation-report-not-found';
   }
-  if (lowerMessage.includes('working spec') || lowerMessage.includes('validation')) {
-    return 'working-spec-validation';
+  // 'spec' (per-feature .caws/specs/<id>.yaml) replaces the v10 'working spec' term.
+  // Match either for compatibility with errors that quote either phrase.
+  if (
+    lowerMessage.includes('spec') ||
+    lowerMessage.includes('validation') ||
+    lowerMessage.includes('schema')
+  ) {
+    return 'spec-validation';
   }
   if (lowerMessage.includes('workspace') || lowerMessage.includes('monorepo')) {
     return 'monorepo-detection';

package/dist/shell/commands/worktree.d.ts

@@ -15,8 +15,7 @@ export interface WorktreeCreateOptions extends BaseCommandOptions {
     readonly branch?: string;
 }
 export declare function runWorktreeCreateCommand(opts: WorktreeCreateOptions): number;
-export interface WorktreeListOptions extends BaseCommandOptions {
-}
+export type WorktreeListOptions = BaseCommandOptions;
 export declare function runWorktreeListCommand(opts?: WorktreeListOptions): number;
 export interface WorktreeBindOptions extends BaseCommandOptions {
     readonly name: string;

package/dist/shell/commands/worktree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../../src/shell/commands/worktree.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,KAAK,SAAS,EAAQ,MAAM,2BAA2B,CAAC;AAcjE,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAkED,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,CAuC5E;AAID,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;CAAG;AAElE,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,mBAAwB,GAAG,MAAM,CAwB7E;AAID,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CA+BxE;AAID,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAkC9E;AAID,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CA0C1E"}
+{"version":3,"file":"worktree.d.ts","sourceRoot":"","sources":["../../../src/shell/commands/worktree.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,KAAK,SAAS,EAAQ,MAAM,2BAA2B,CAAC;AAcjE,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAkED,MAAM,WAAW,qBAAsB,SAAQ,kBAAkB;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,CAuC5E;AAID,MAAM,MAAM,mBAAmB,GAAG,kBAAkB,CAAC;AAErD,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,mBAAwB,GAAG,MAAM,CAwB7E;AAID,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CA+BxE;AAID,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAED,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAkC9E;AAID,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CA0C1E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paths.design/caws-cli",
-  "version": "11.1.1",
+  "version": "11.1.3",
   "description": "CAWS CLI - the governed core for CAWS project state, scope, claims, gates, waivers, and evidence (v11.1). Restores canonical spec/worktree lifecycle on the vNext kernel/store/shell architecture.",
   "main": "dist/index.js",
   "bin": {

package/templates/hook-packs/claude-code/classify_command.py

@@ -71,14 +71,14 @@ DENY_SEGMENT_PATTERNS: list[tuple[str, str]] = [
     (r"\binit\s+[06]\b", "system runlevel change"),
     # CAWS spec/policy/waiver protection (RC defect #8).
     # Naked rm/mv on .caws/specs/, .caws/policy.yaml, or .caws/waivers/ bypasses
-    # the audit trail. Use `caws specs delete|archive`, `caws waivers revoke`,
+    # the audit trail. Use `caws specs close|archive`, `caws waiver revoke`,
     # or edit policy.yaml in place via Edit (not Bash) instead.
     (r"\b(rm|mv)\b[^\n]*\.caws/specs/[^\s'\"]*\.ya?ml\b",
-     "naked rm/mv on .caws/specs/*.yaml — use `caws specs delete|archive <id>`"),
+     "naked rm/mv on .caws/specs/*.yaml — use `caws specs close|archive <id>`"),
     (r"\b(rm|mv)\b[^\n]*\.caws/policy\.ya?ml\b",
      "naked rm/mv on .caws/policy.yaml — policy is governed; use Edit and a CAWS waiver"),
     (r"\b(rm|mv)\b[^\n]*\.caws/waivers/[^\s'\"]*\.ya?ml\b",
-     "naked rm/mv on .caws/waivers/*.yaml — use `caws waivers revoke <id>`"),
+     "naked rm/mv on .caws/waivers/*.yaml — use `caws waiver revoke <id>`"),
 ]
 
 # Segment-level regex patterns that require user confirmation.