docs: add planning and architecture documentation

Add comprehensive planning documents and specifications:

Planning documents:
- diff-command-plans/: Implementation plans for diff command refactoring
- Agent-based planning approach for codebase exploration, e2e testing, and documentation

Architecture and specifications:
- High-level design (HLD) and context documents
- CLI specification and command structure
- Orchestrator and agent plans (research, CLI core, governance engines)
- GitHub Action agent implementation plan
- E2E testing strategy
- Documentation website plans (v1 and v2)
- differs.json-schema package specification
- Ecosystem analysis report

These documents provide the foundation for the Contractual architecture and guide future development efforts.

Author: omermorad

diff-command-plans/01-codebase-agent.md

@@ -0,0 +1,323 @@
+# Codebase Agent: Add `contractual diff` Command
+
+## Context
+
+Add a new `diff` command that shows all classified changes between schema versions. The command hierarchy becomes:
+
+```
+diff        → "Show me everything that changed, classified"
+breaking    → "Are there breaking changes? Block if yes"    (uses diff internally)
+changeset   → "Generate a changeset from changes"           (uses diff internally)
+```
+
+`diff` is the primitive. `breaking` and `changeset` are opinions on top of it.
+
+---
+
+## Tasks
+
+### Task 1: Extract shared diffing logic
+
+**Create:** `packages/cli/src/core/diff.ts`
+
+Currently, the diffing logic lives inside `breaking.command.ts`. Extract it into a shared module.
+
+```typescript
+import type { ResolvedConfig, DiffResult } from '@contractual/types';
+
+export interface DiffOptions {
+  contracts?: string[];  // filter to specific contracts
+}
+
+/**
+ * Core diffing function. Runs the appropriate differ for each contract,
+ * comparing current spec against last versioned snapshot.
+ *
+ * Returns classified changes for all contracts.
+ * This is the primitive that `diff`, `breaking`, and `changeset` all use.
+ */
+export async function diffContracts(
+  config: ResolvedConfig,
+  options?: DiffOptions
+): Promise<DiffResult[]> {
+  // 1. Filter to requested contracts (or all)
+  // 2. For each contract:
+  //    a. Find snapshot (getSnapshotPath)
+  //    b. If no snapshot: return empty DiffResult (first version, no changes)
+  //    c. If breaking === false: skip (disabled)
+  //    d. Resolve differ (getDiffer from governance)
+  //    e. Run differ: snapshot (old) vs current spec (new)
+  //    f. Collect DiffResult with contract name
+  // 3. Return DiffResult[]
+}
+```
+
+---
+
+### Task 2: Create diff command
+
+**Create:** `packages/cli/src/commands/diff.command.ts`
+
+```typescript
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadConfig } from '../config/index.js';
+import { diffContracts } from '../core/diff.js';
+import { formatDiffText, formatDiffJson } from '../formatters/diff.js';
+
+export function diffCommand(): Command {
+  return new Command('diff')
+    .description('Show all changes between current specs and last versioned snapshots')
+    .option('--contract <name>', 'Diff only one contract')
+    .option('--format <format>', 'Output format: text, json', 'text')
+    .option('--severity <level>', 'Filter: all, breaking, non-breaking, patch', 'all')
+    .option('--verbose', 'Show JSON Pointer paths for each change')
+    .action(async (options) => {
+      try {
+        const config = loadConfig();
+        const results = await diffContracts(config, {
+          contracts: options.contract ? [options.contract] : undefined,
+        });
+
+        // Apply severity filter
+        const filtered = filterBySeverity(results, options.severity);
+
+        if (options.format === 'json') {
+          console.log(formatDiffJson(filtered));
+        } else {
+          formatDiffText(filtered, { verbose: options.verbose });
+        }
+
+        // diff always exits 0 on success
+        process.exitCode = 0;
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error';
+        console.error(chalk.red('Error:'), message);
+        process.exitCode = 2; // config error
+      }
+    });
+}
+
+function filterBySeverity(results: DiffResult[], severity: string): DiffResult[] {
+  if (severity === 'all') return results;
+
+  return results.map(r => {
+    const filteredChanges = r.changes.filter(c => c.severity === severity);
+    return {
+      ...r,
+      changes: filteredChanges,
+      summary: recalculateSummary(filteredChanges),
+    };
+  });
+}
+
+function recalculateSummary(changes: Change[]): DiffSummary {
+  return {
+    breaking: changes.filter(c => c.severity === 'breaking').length,
+    nonBreaking: changes.filter(c => c.severity === 'non-breaking').length,
+    patch: changes.filter(c => c.severity === 'patch').length,
+    unknown: changes.filter(c => c.severity === 'unknown').length,
+  };
+}
+```
+
+**Exit codes:**
+- 0: Success (always, regardless of changes found)
+- 2: Configuration error
+- 3: Tool execution error
+
+---
+
+### Task 3: Create diff formatter
+
+**Create:** `packages/cli/src/formatters/diff.ts`
+
+```typescript
+import chalk from 'chalk';
+import type { DiffResult, Change, ChangeSeverity } from '@contractual/types';
+
+export interface FormatOptions {
+  verbose?: boolean;
+}
+
+export function formatDiffText(results: DiffResult[], options: FormatOptions = {}): void {
+  for (const result of results) {
+    if (result.changes.length === 0) {
+      console.log(`${chalk.cyan(result.contract)}: ${chalk.dim('no changes')}`);
+      console.log();
+      continue;
+    }
+
+    // Header: contract name + summary
+    const parts: string[] = [];
+    if (result.summary.breaking > 0) parts.push(`${result.summary.breaking} breaking`);
+    if (result.summary.nonBreaking > 0) parts.push(`${result.summary.nonBreaking} non-breaking`);
+    if (result.summary.patch > 0) parts.push(`${result.summary.patch} patch`);
+    if (result.summary.unknown > 0) parts.push(`${result.summary.unknown} unknown`);
+
+    const bumpColor = result.suggestedBump === 'major' ? chalk.red
+      : result.suggestedBump === 'minor' ? chalk.yellow
+      : chalk.green;
+
+    console.log(
+      `${chalk.cyan(result.contract)}: ${result.changes.length} changes (${parts.join(', ')}) — suggested bump: ${bumpColor(result.suggestedBump)}`
+    );
+    console.log();
+
+    // Each change
+    for (const change of result.changes) {
+      const label = formatSeverityLabel(change.severity);
+      console.log(`  ${label} ${change.message}`);
+      if (options.verbose && change.path) {
+        console.log(`${' '.repeat(14)}path: ${chalk.dim(change.path)}`);
+      }
+    }
+    console.log();
+  }
+}
+
+function formatSeverityLabel(severity: ChangeSeverity): string {
+  switch (severity) {
+    case 'breaking':
+      return chalk.red.bold('BREAKING'.padEnd(12));
+    case 'non-breaking':
+      return chalk.yellow('non-breaking');
+    case 'patch':
+      return chalk.green('patch'.padEnd(12));
+    case 'unknown':
+      return chalk.gray('unknown'.padEnd(12));
+  }
+}
+
+export function formatDiffJson(results: DiffResult[]): string {
+  return JSON.stringify({ results }, null, 2);
+}
+```
+
+**Expected output:**
+```
+orders-api: 3 changes (2 breaking, 1 non-breaking) — suggested bump: major
+
+  BREAKING     Removed endpoint GET /orders/{id}/details
+               path: /paths/~1orders~1{id}~1details/get
+  BREAKING     Changed type of field 'amount': string → number
+               path: /components/schemas/Order/properties/amount/type
+  non-breaking Added optional field 'tracking_url'
+               path: /components/schemas/Order/properties/tracking_url
+
+order-schema: no changes
+```
+
+---
+
+### Task 4: Refactor breaking command
+
+**Modify:** `packages/cli/src/commands/breaking.command.ts`
+
+Remove the inline diffing logic. Replace with:
+
+```typescript
+import { diffContracts } from '../core/diff.js';
+
+// In the action handler:
+const results = await diffContracts(config, {
+  contracts: options.contract ? [options.contract] : undefined,
+});
+
+const hasBreaking = results.some(r => r.summary.breaking > 0);
+
+// ... existing output formatting ...
+
+// Exit code logic stays here:
+if (failOn === 'breaking' && hasBreaking) {
+  process.exitCode = 1;
+} else if (failOn === 'non-breaking' && results.some(r => r.summary.nonBreaking > 0)) {
+  process.exitCode = 1;
+} else if (failOn === 'any' && results.some(r => r.changes.length > 0)) {
+  process.exitCode = 1;
+}
+```
+
+The output format of `breaking` stays the same. The only change is internal — it calls `diffContracts()` instead of having its own diffing code.
+
+---
+
+### Task 5: Refactor changeset command
+
+**Modify:** `packages/cli/src/commands/changeset.command.ts`
+
+Replace the inline diff logic with:
+
+```typescript
+import { diffContracts } from '../core/diff.js';
+
+// In the action handler, replace the diff loop with:
+const diffResults = await diffContracts(config);
+
+// Filter to only results with changes
+const resultsWithChanges = diffResults.filter(r => r.changes.length > 0);
+
+if (resultsWithChanges.length === 0) {
+  diffSpinner.succeed('No changes detected');
+  console.log(chalk.gray('No changeset created.'));
+  process.exit(0);
+}
+
+// ... rest of changeset generation uses resultsWithChanges ...
+```
+
+---
+
+### Task 6: Register diff command
+
+**Modify:** `packages/cli/src/commands.ts`
+
+Add `diff` between `lint` and `breaking`:
+
+```typescript
+import { diffCommand } from './commands/diff.command.js';
+
+// In program setup, after lint, before breaking:
+program.addCommand(diffCommand());
+```
+
+Command order should be:
+1. init
+2. lint
+3. diff (NEW)
+4. breaking
+5. changeset
+6. version
+7. status
+
+---
+
+## File Structure After Implementation
+
+```
+packages/cli/src/
+├── core/
+│   └── diff.ts                  # NEW - shared diffing logic
+├── commands/
+│   ├── init.command.ts
+│   ├── lint.command.ts
+│   ├── diff.command.ts          # NEW
+│   ├── breaking.command.ts      # MODIFIED
+│   ├── changeset.command.ts     # MODIFIED
+│   ├── version.command.ts
+│   └── status.command.ts
+├── formatters/
+│   └── diff.ts                  # NEW
+└── commands.ts                  # MODIFIED
+```
+
+---
+
+## Verification
+
+1. `pnpm build` - All packages build
+2. `node packages/cli/dist/commands.js diff --help` - Shows options
+3. `node packages/cli/dist/commands.js diff` - Shows changes or "no changes"
+4. `node packages/cli/dist/commands.js diff --format json` - Valid JSON
+5. `node packages/cli/dist/commands.js breaking` - Still works as before
+6. `node packages/cli/dist/commands.js changeset` - Still works as before