feat(tools): add loop-sync CLI for drift detection and configuration …

.gitignore

@@ -48,3 +48,4 @@ state.json
 !starters/**/.codex/
 !starters/**/.codex/**
 *.session
+!tools/loop-sync/dist/

package.json

@@ -8,11 +8,12 @@
     "test:loop-audit": "cd tools/loop-audit && npm test",
     "test:loop-init": "cd tools/loop-init && npm test",
     "test:loop-cost": "cd tools/loop-cost && npm test",
-    "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost",
-    "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build"
+    "test:loop-sync": "cd tools/loop-sync && npm test",
+    "test:tools": "npm run test:loop-audit && npm run test:loop-init && npm run test:loop-cost && npm run test:loop-sync",
+    "build:tools": "cd tools/loop-audit && npm run build && cd ../loop-init && npm run build && cd ../loop-cost && npm run build && cd ../loop-sync && npm run build"
   },
   "devDependencies": {
     "ajv": "^8.17.1",
     "yaml": "^2.8.0"
   }
-}
+}

tools/loop-sync/README.md

@@ -0,0 +1,115 @@
+# loop-sync
+
+Detect and sync drift between Loop configuration files in your repository.
+
+## Why loop-sync?
+
+When working in teams, Loop configurations can drift over time:
+
+- STATE.md and LOOP.md get out of sync
+- Skills are updated but not reflected in configuration
+- Required files are missing
+- Configuration drifts from starters
+
+`loop-sync` detects these issues and provides actionable suggestions.
+
+## Installation
+
+```bash
+npm install -g @cobusgreyling/loop-sync
+# or
+npx @cobusgreyling/loop-sync .
+```
+
+## Usage
+
+```bash
+loop-sync [target-dir] [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-a, --auto-fix` | Attempt to auto-fix issues (experimental) |
+| `-d, --dry-run` | Show what would be done without making changes |
+| `-v, --verbose` | Show detailed information |
+| `--json` | Output JSON format |
+| `-h, --help` | Show help |
+
+### Examples
+
+```bash
+# Basic sync check
+loop-sync .
+
+# Verbose output
+loop-sync ./my-project -v
+
+# JSON output for scripting
+loop-sync ./my-project --json
+```
+
+## What it checks
+
+1. **Required files**
+   - STATE.md (required)
+   - LOOP.md (required)
+   - AGENTS.md (recommended)
+
+2. **STATE.md ↔ LOOP.md consistency**
+   - Structural similarity
+   - State file references
+   - Pattern consistency
+
+3. **Skills directory**
+   - Existence of `.claude/skills/`
+   - Version information in SKILL.md files
+
+4. **Configuration drift**
+   - Missing references
+   - Orphaned files
+   - Inconsistencies
+
+## Score Interpretation
+
+| Score | Level | Meaning |
+|-------|-------|---------|
+| 90-100 | Healthy | No issues detected |
+| 70-89 | Warning | Minor inconsistencies |
+| 0-69 | Critical | Major issues need attention |
+
+## Output Example
+
+```
+Loop Sync Report
+══════════════════════════════════════════════════
+Score: 85/100 (healthy)
+
+✅ No issues detected. Configuration is consistent.
+
+💡 Suggestions:
+   - Run loop-init to scaffold missing files
+```
+
+## Integration with CI/CD
+
+Add to your GitHub Actions workflow:
+
+```yaml
+- name: Run loop-sync
+  run: npx @cobusgreyling/loop-sync .
+```
+
+## Development
+
+```bash
+cd tools/loop-sync
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

tools/loop-sync/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Loop Sync CLI
+ *
+ * Detect and sync drift between Loop configuration files
+ */
+export {};

tools/loop-sync/dist/cli.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Loop Sync CLI
+ *
+ * Detect and sync drift between Loop configuration files
+ */
+import { runSync, formatReport } from './sync.js';
+function parseArgs(argv) {
+    let targetDir = '.';
+    let autoFix = false;
+    let dryRun = false;
+    let verbose = false;
+    let json = false;
+    let help = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--help' || a === '-h')
+            help = true;
+        else if (a === '--auto-fix' || a === '-a')
+            autoFix = true;
+        else if (a === '--dry-run' || a === '-d')
+            dryRun = true;
+        else if (a === '--verbose' || a === '-v')
+            verbose = true;
+        else if (a === '--json')
+            json = true;
+        else if (!a.startsWith('-'))
+            targetDir = a;
+    }
+    return { targetDir, autoFix, dryRun, verbose, help };
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        console.log(`loop-sync — detect and sync drift between Loop configuration files
+
+Usage:
+  loop-sync [target-dir] [options]
+
+Options:
+  -a, --auto-fix    Attempt to auto-fix issues (experimental)
+  -d, --dry-run     Show what would be done without making changes
+  -v, --verbose     Show detailed information
+  --json            Output JSON format
+  -h, --help        Show this help
+
+Examples:
+  loop-sync .
+  loop-sync ./my-project -v
+  loop-sync ./my-project --json
+
+The tool checks:
+  - STATE.md ↔ LOOP.md consistency
+  - Required files (STATE.md, LOOP.md, AGENTS.md)
+  - Skills directory structure
+  - Configuration drift indicators
+
+Score interpretation:
+  - 90-100: Healthy (no issues)
+  - 70-89: Warning (minor inconsistencies)
+  - 0-69: Critical (major issues need attention)
+
+Docs: https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-sync
+`);
+        process.exit(0);
+    }
+    try {
+        const report = await runSync(args);
+        if (args.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(formatReport(report));
+        }
+        // Exit with appropriate code
+        if (report.level === 'critical') {
+            process.exit(1);
+        }
+        else if (report.level === 'warning') {
+            process.exit(2);
+        }
+    }
+    catch (error) {
+        console.error('loop-sync failed:', error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+main();

tools/loop-sync/dist/sync.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Loop Sync - Detect and sync drift between Loop configuration files
+ *
+ * This module detects:
+ * 1. STATE.md ↔ LOOP.md consistency
+ * 2. Skills version updates
+ * 3. Missing required files
+ * 4. Configuration drift from starters
+ */
+export interface DriftReport {
+    score: number;
+    level: 'healthy' | 'warning' | 'critical';
+    issues: DriftIssue[];
+    suggestions: string[];
+    timestamp: string;
+}
+export interface DriftIssue {
+    type: 'missing' | 'outdated' | 'inconsistent' | 'orphaned';
+    file: string;
+    message: string;
+    severity: 'error' | 'warning' | 'info';
+    suggestion?: string;
+}
+export interface SyncOptions {
+    targetDir: string;
+    autoFix: boolean;
+    dryRun: boolean;
+    verbose: boolean;
+    help?: boolean;
+    json?: boolean;
+}
+/**
+ * Main sync function
+ */
+export declare function runSync(options: SyncOptions): Promise<DriftReport>;
+/**
+ * Format report for CLI output
+ */
+export declare function formatReport(report: DriftReport): string;