@oleksandr.rudnychenko/sync_loop 0.2.2 → 0.2.4

package/README.md

@@ -1,124 +1,246 @@
-# SyncLoop
-
-MCP server that gives AI coding agents a self-correcting reasoning protocol.
-
-Works with **GitHub Copilot**, **Cursor**, and **Claude Code** — any client that supports [Model Context Protocol](https://modelcontextprotocol.io/).
-
-## Quick Start
-
-Add to your MCP client configuration:
-
-```json
-{
-  "mcpServers": {
-    "syncloop": {
-      "command": "npx",
-      "args": ["-y", "syncloop"]
-    }
-  }
-}
-```
-
-That's it. Your AI agent now has access to the full SyncLoop reasoning protocol.
-
-### Where to add MCP config
-
-| Client | Config location |
-|--------|----------------|
-| **VS Code (Copilot)** | `.vscode/mcp.json` or Settings → MCP Servers |
-| **Cursor** | Settings → MCP Servers |
-| **Claude Desktop** | `claude_desktop_config.json` |
-| **Claude Code** | `claude_code_config.json` or `--mcp-config` flag |
-
-## What it provides
-
-### Resources (protocol docs, served on-demand)
-
-| Resource | Content |
-|----------|---------|
-| `reasoning-kernel` | Core 7-stage loop, transition map, context clearage |
-| `feedback` | Failure diagnosis, patch protocol, branch pruning |
-| `validate-env` | Stage 1 NFR gates (types, tests, layers, complexity) |
-| `validate-n` | Stage 2 neighbor checks (shapes, boundaries, bridges) |
-| `patterns` | Pattern routing index and learned patterns |
-| `glossary` | Canonical terminology and naming rules |
-| `code-patterns` | P1–P11 implementation patterns |
-| `testing-guide` | Test pyramid, fixtures, mocks, strategies |
-| `refactoring-workflow` | 4-phase safe refactoring checklist |
-| `api-standards` | Boundary contracts and versioning |
-| `protocol-summary` | Condensed protocol overview (~50 lines) |
-| `agents-md` | AGENTS.md entrypoint template |
-| `overview` | File index and framework overview |
-
-### Tools
-
-| Tool | Description |
-|------|-------------|
-| `init` | Scaffold platform-specific files into your project (`.github/instructions/`, `.cursor/rules/`, `.claude/rules/`) |
-
-### Prompts
-
-| Prompt | Description |
-|--------|-------------|
-| `bootstrap` | Wire SyncLoop to your project — scans codebase and fills in project-specific details |
-| `protocol` | Condensed reasoning protocol for system-level injection |
-
-## Protocol Overview
-
-Every agent turn follows a 7-stage loop:
-
-```
-SENSE → GKP → DECIDE+ACT → CHALLENGE-TEST → UPDATE → LEARN → REPORT
-```
-
-| Stage | Purpose |
-|-------|---------|
-| **SENSE** | Detect state, issues, context gaps |
-| **GKP** | Gather knowledge, compress into constraints + risks |
-| **DECIDE+ACT** | Select mode, plan, execute immediately |
-| **CHALLENGE-TEST** | 2-stage validation (ENV gates + NEIGHBOR checks) |
-| **UPDATE** | Commit state transitions |
-| **LEARN** | Persist fixes and patterns |
-| **REPORT** | Session summary (skip if trivial) |
-
-Three operational modes:
-
-| Mode | Trigger |
-|------|---------|
-| **INTACT-STABILIZE** | All gates pass → harden quality |
-| **BROKEN-EXPAND** | Issues detected → fix root cause |
-| **OVERDENSE-SPLIT** | Complexity high → decompose first |
-
-## Scaffolding (optional)
-
-If you also want the protocol files in your project (for offline use or customization), use the `init` tool:
-
-```
-Use the syncloop init tool to scaffold files for copilot/cursor/claude/all
-```
-
-When an AI agent performs this step, it should ask first:
-"Which SyncLoop target platform should I scaffold: `copilot`, `cursor`, `claude`, or `all`?"
-
-This creates:
-
-| Target | Files generated |
-|--------|----------------|
-| `copilot` | `.github/copilot-instructions.md` + `.github/instructions/*.instructions.md` |
-| `cursor` | `.cursor/rules/*.md` with proper frontmatter |
-| `claude` | `CLAUDE.md` + `.claude/rules/*.md` with `paths` frontmatter |
-| `all` | All of the above |
-
-Plus `AGENTS.md` (cross-platform entrypoint) and `.agent-loop/` (canonical source).
-
-## Bootstrap
-
-After scaffolding, use the `bootstrap` prompt to wire SyncLoop to your actual project:
-
-1. Ask the agent to use the **bootstrap** prompt
-2. The agent scans your codebase structure and fills in project-specific details
-3. `AGENTS.md`, validation commands, patterns, and glossary get wired to real code
-
-## License
-
-MIT
+# SyncLoop
+
+**Give your AI coding agent a structured reasoning loop.**
+
+Without a protocol, AI agents guess — they hallucinate fixes, ignore architecture rules, fail silently, and lose context across a long session. SyncLoop solves this by wiring a strict 7-stage reasoning loop directly into your agent via MCP, so every task goes through sense → plan → act → validate → learn, every turn.
+
+Works with **GitHub Copilot**, **Cursor**, and **Claude Code** — any client that supports [Model Context Protocol](https://modelcontextprotocol.io/).
+
+---
+
+## Why it matters
+
+| Without SyncLoop | With SyncLoop |
+|------------------|---------------|
+| Agent jumps straight to coding | Agent senses state and gaps first |
+| Fixes symptoms, not root causes | Diagnoses root cause before patching |
+| Ignores architecture layers | Enforces layer rules on every change |
+| Loses context in long sessions | Compresses and clears context each cycle |
+| Repeats the same mistakes | Learns from failures, persists heuristics |
+| No self-correction on test failures | Retries with targeted patches (max 5 iterations) |
+
+---
+
+## Quick Start
+
+Add to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "sync_loop": {
+      "command": "npx",
+      "args": ["-y", "-p", "@oleksandr.rudnychenko/sync_loop", "sync_loop"]
+    }
+  }
+}
+```
+
+That's it. Your agent now runs the full SyncLoop protocol on every turn.
+
+### Where to add the config
+
+| Client | Config location |
+|--------|----------------|
+| **VS Code (Copilot)** | `.vscode/mcp.json` or Settings → MCP Servers |
+| **Cursor** | Settings → MCP Servers |
+| **Claude Desktop** | `claude_desktop_config.json` |
+| **Claude Code** | `claude_code_config.json` or `--mcp-config` flag |
+
+---
+
+## How the Agent Loop Works
+
+Every agent turn runs the same 7-stage loop — no shortcuts:
+
+```
+SENSE → GKP → DECIDE+ACT → CHALLENGE-TEST → UPDATE → LEARN → REPORT
+```
+
+### Stage by stage
+
+**1. SENSE**
+Before touching any code, the agent reads the current codebase state and identifies:
+- what needs to change
+- what could break
+- what context is still missing
+
+It will not proceed until it has enough information to act safely.
+
+**2. GKP — Generated Knowledge Pack**
+The agent routes through a pattern registry to pull only the constraints, risks, and implementation
+examples relevant to this specific task. Raw files are not carried forward — only a compressed,
+task-scoped context bundle is produced.
+
+**3. DECIDE + ACT**
+The agent selects one of three operational modes and executes immediately:
+
+| Mode | When | What the agent does |
+|------|------|---------------------|
+| **INTACT-STABILIZE** | System is healthy | Harden types, add tests, improve docs |
+| **BROKEN-EXPAND** | Something is broken | Patch the root cause with minimal surface area |
+| **OVERDENSE-SPLIT** | Code is too complex | Decompose before adding anything new |
+
+Plan and action happen in the same step — no plans without execution.
+
+**4. CHALLENGE-TEST**
+Two validation gates run in a loop until everything passes or the retry budget runs out (max 5):
+
+1. **ENV gate** — type safety, test coverage, layer integrity, complexity thresholds, debug hygiene
+2. **NEIGHBOR gate** — shape compatibility across modules, boundary exports, cross-module contracts
+
+Failures are classified before any fix is attempted:
+
+| Class | Signal | What happens |
+|-------|--------|--------------|
+| **Micro** | Error text directly explains fix (missing return type, stray `print()`) | Fixed in-place, no budget consumed |
+| **Macro** | Root cause needs diagnosis (test failure, layer violation) | Patch cycle runs, consumes 1 of 5 retries |
+
+If the same failure recurs 3 times, the approach is pruned and the agent re-enters planning
+with a hardcoded constraint against repeating it. If it was already pruned once, the agent escalates.
+
+**5. UPDATE**
+Once all gates pass, state transitions are committed: changed files, updated contracts, modified patterns.
+
+**6. LEARN**
+Lessons from the cycle are persisted so they carry into future turns:
+- Quick fix → added as a row in the auto-fixes or common errors table
+- New reusable approach → written into the matching pattern spec
+
+**7. REPORT**
+Non-trivial tasks produce a structured session summary: what changed, which gates passed, what was learned.
+Skipped for trivial one-liners.
+
+---
+
+## Context Compaction
+
+Long coding sessions degrade agent quality when too much raw context accumulates.
+SyncLoop actively manages this with two strategies:
+
+**State Collapse — after a successful cycle**
+Everything is summarised into a compact checkpoint. Only that checkpoint enters the next SENSE stage.
+Raw history is discarded.
+
+**Branch Pruning — on repeated failure**
+When the same error recurs 3 times, the failing approach is reverted and a constraint is recorded:
+"do not retry approach X". The agent re-enters DECIDE with that lesson injected.
+
+This keeps the agent sharp in long sessions instead of degrading.
+
+---
+
+## Pattern System
+
+SyncLoop routes implementation decisions through a structured registry rather than letting the agent free-associate.
+
+### Pattern families
+
+| ID | What it covers |
+|----|----------------|
+| **P1–P11** | Port/adapter, domain modules, background tasks, transport routes, dependency injection, typed models, enum safety, error handling, type hints, service orchestration, config isolation |
+| **R1** | 4-phase safe refactoring: plan → execute → validate → document |
+| **R2** | Full test pyramid: unit, integration, API — fixtures, factories, mocks, naming conventions |
+| **R3** | API boundary contracts: typed request/response models, error envelopes, versioning |
+
+### How pattern routing works
+
+Inside GKP, the agent:
+1. Scans pattern triggers (`"Use when: moving a file"`, `"Use when: adding an endpoint"`)
+2. Routes to the matching spec
+3. Extracts constraints and examples for the active task only
+4. Checks learned tables for known pitfalls and auto-fixes
+5. Compresses to a minimal action context
+
+This makes decisions consistent across the session and prevents architecture drift.
+
+---
+
+## Testing Approach
+
+Tests are run in order: changed files first → adjacent modules → full suite.
+The agent never modifies tests to make them pass. If a test fails, the source is fixed.
+
+**Failure handling:**
+- Missing return types, stray debug calls → fixed inline, no retry budget spent
+- Real test failures or layer violations → root-cause diagnosis → targeted patch → retry gate
+
+**Test pyramid targets:** ≥70% unit, ≤20% integration, ≤10% API.
+
+---
+
+## Guardrails
+
+The agent is hardcoded never to:
+
+- Modify tests to force them green
+- Remove type annotations to silence type errors
+- Bypass architecture layer boundaries
+- Change public APIs or contracts without explicit user approval
+- Mix refactoring with feature changes in the same patch
+- Skip validation after refactors, import moves, or interface changes
+
+If any of these are required to proceed, the agent stops and escalates.
+
+---
+
+## What the MCP server exposes
+
+### Resources
+
+All protocol docs are served on-demand — the agent pulls only what it needs per stage.
+
+| Resource | Content |
+|----------|---------|
+| `reasoning-kernel` | Full 7-stage loop, transition map, stage details, context clearage |
+| `feedback` | Failure diagnosis, patch contract, micro-loop, branch pruning, learning |
+| `validate-env` | Stage 1 gates: types, tests, layers, complexity, debug hygiene |
+| `validate-n` | Stage 2 gates: shape compatibility, boundaries, bridge contracts |
+| `patterns` | Pattern routing index, GKP table, auto-fixes, heuristics, pruning records |
+| `glossary` | Canonical domain terminology and naming rules |
+| `code-patterns` | P1–P11 implementation patterns with examples |
+| `testing-guide` | Full test strategy: pyramid, fixtures, factories, mocks, parametrize |
+| `refactoring-workflow` | 4-phase refactoring checklist |
+| `api-standards` | Boundary contracts: typed models, error envelopes, versioning |
+| `protocol-summary` | Condensed ~50-line overview for system-prompt injection |
+| `agents-md` | AGENTS.md entrypoint template |
+| `overview` | File index and framework overview |
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `init` | Scaffold platform-specific protocol files into your project |
+
+### Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `bootstrap` | Wire SyncLoop to your actual project — scans codebase, populates real commands and architecture |
+| `protocol` | Condensed protocol for direct system-prompt injection |
+
+---
+
+## Optional: scaffold files into your project
+
+For offline use, CI, or customisation, the full protocol can be written into your repo:
+
+```
+Use the sync_loop init tool — choose: copilot, cursor, claude, or all
+```
+
+| Target | Files generated |
+|--------|----------------|
+| `copilot` | `.github/copilot-instructions.md` + `.github/instructions/*.instructions.md` |
+| `cursor` | `.cursor/rules/*.md` with frontmatter |
+| `claude` | `CLAUDE.md` + `.claude/rules/*.md` |
+| `all` | All of the above + `AGENTS.md` + `.agent-loop/` canonical source |
+
+After scaffolding, use the `bootstrap` prompt so the agent scans your codebase and populates
+the generated files with real validation commands, architecture layers, and module boundaries.
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -1,77 +1,131 @@
-#!/usr/bin/env node
-
-const args = process.argv.slice(2);
-const command = args[0];
-
-// ---------------------------------------------------------------------------
-// Help
-// ---------------------------------------------------------------------------
-if (args.includes("--help") || args.includes("-h")) {
-  process.stdout.write(`
-syncloop — MCP server + CLI for the SyncLoop agent reasoning protocol
-
-Usage:
-  npx syncloop                              Start MCP server (stdio transport)
-  npx syncloop init [--target <platform>]   Scaffold files into current project
-  npx syncloop --help                       Show this help
-
-Init targets:
-  copilot   .github/instructions/ + copilot-instructions.md
-  cursor    .cursor/rules/ with frontmatter
-  claude    CLAUDE.md + .claude/rules/
-  all       All of the above (default)
-
-MCP Configuration (add to your client settings):
-
-  {
-    "mcpServers": {
-      "sync_loop": {
-        "command": "npx",
-        "args": ["-y", "@oleksandr.rudnychenko/sync_loop"]
-      }
-    }
-  }
-
-Resources:  Protocol docs on-demand (reasoning kernel, validation, feedback, patterns)
-Tools:      init — scaffold platform-specific files
-Prompts:    bootstrap — wire SyncLoop to your project; protocol — reasoning loop
-
-https://github.com/nicekid1/syncloop
-`);
-  process.exit(0);
-}
-
-// ---------------------------------------------------------------------------
-// CLI: npx syncloop init
-// ---------------------------------------------------------------------------
-if (command === "init") {
-  const targetIdx = args.indexOf("--target");
-  const target = targetIdx !== -1 && args[targetIdx + 1] ? args[targetIdx + 1] : "all";
-  const validTargets = ["copilot", "cursor", "claude", "all"];
-
-  if (!validTargets.includes(target)) {
-    process.stderr.write(`Error: unknown target "${target}". Use one of: ${validTargets.join(", ")}\n`);
-    process.exit(1);
-  }
-
-  const { init } = await import("../src/init.js");
-
-  // Positional arg after flags = project path; default to cwd
-  const positional = args.slice(1).filter(a => !a.startsWith("--") && a !== target);
-  const projectPath = positional[0] || process.cwd();
-
-  try {
-    const results = init(projectPath, target);
-    process.stdout.write(`SyncLoop initialized for ${target}:\n\n${results.join("\n")}\n\nDone. Run the bootstrap prompt to wire to your project.\n`);
-  } catch (err) {
-    process.stderr.write(`Error: ${err.message}\n`);
-    process.exit(1);
-  }
-
-  process.exit(0);
-}
-
-// ---------------------------------------------------------------------------
-// Default: start MCP server
-// ---------------------------------------------------------------------------
-import("../src/server.js");
+#!/usr/bin/env node
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+function getOptionValue(optionName) {
+  const idx = args.indexOf(optionName);
+  if (idx === -1) return undefined;
+  return args[idx + 1];
+}
+
+function getPositionalArgs() {
+  const positionals = [];
+  for (let i = 1; i < args.length; i += 1) {
+    const current = args[i];
+    if (current === "--target") {
+      i += 1;
+      continue;
+    }
+    if (current === "--dry-run" || current === "--overwrite" || current === "--no-overwrite") {
+      continue;
+    }
+    if (current.startsWith("--")) {
+      continue;
+    }
+    positionals.push(current);
+  }
+  return positionals;
+}
+
+// ---------------------------------------------------------------------------
+// Help
+// ---------------------------------------------------------------------------
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(`
+sync_loop - MCP server + CLI for the SyncLoop agent reasoning protocol
+
+Usage:
+  npx -y -p @oleksandr.rudnychenko/sync_loop sync_loop
+    Start MCP server (stdio transport)
+
+  npx -y -p @oleksandr.rudnychenko/sync_loop sync_loop init [projectPath] [--target <platform>] [--dry-run] [--no-overwrite]
+    Scaffold files into the project
+
+  npx -y -p @oleksandr.rudnychenko/sync_loop sync_loop --help
+    Show this help
+
+Init targets:
+  copilot   .github/instructions/ + copilot-instructions.md
+  cursor    .cursor/rules/ with frontmatter
+  claude    CLAUDE.md + .claude/rules/
+  all       All of the above (default)
+
+Flags:
+  --dry-run       Preview writes without modifying files
+  --no-overwrite  Do not overwrite existing generated files
+
+MCP Configuration (add to your client settings):
+
+  {
+    "mcpServers": {
+      "sync_loop": {
+        "command": "npx",
+        "args": ["-y", "-p", "@oleksandr.rudnychenko/sync_loop", "sync_loop"]
+      }
+    }
+  }
+
+Resources:  Protocol docs on-demand (reasoning kernel, validation, feedback, patterns)
+Tools:      init - scaffold platform-specific files
+Prompts:    bootstrap - wire SyncLoop to your project; protocol - reasoning loop
+
+https://github.com/oleksandr-rud/SyncLoop
+`);
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// CLI: npx sync_loop init
+// ---------------------------------------------------------------------------
+if (command === "init") {
+  const target = getOptionValue("--target") ?? "all";
+  const dryRun = args.includes("--dry-run");
+  const overwrite = args.includes("--no-overwrite") ? false : true;
+  const validTargets = ["copilot", "cursor", "claude", "all"];
+
+  if (!validTargets.includes(target)) {
+    process.stderr.write(`Error: unknown target "${target}". Use one of: ${validTargets.join(", ")}\n`);
+    process.exit(1);
+  }
+
+  const [projectPath] = getPositionalArgs();
+  const resolvedProjectPath = projectPath || process.cwd();
+
+  const { init, detectStacks } = await import("../src/init.js");
+
+  try {
+    const stacks = detectStacks(resolvedProjectPath);
+    const result = init(
+      resolvedProjectPath,
+      target,
+      stacks,
+      { dryRun, overwrite },
+    );
+
+    process.stdout.write([
+      `SyncLoop initialized for ${target}:`,
+      "",
+      ...result.results,
+      "",
+      "Detected stacks:",
+      ...result.stacks.map((stack) => `- ${stack.name}${stack.path ? ` (${stack.path})` : ""}: ${stack.languages.join(", ")} | ${stack.frameworks.join(", ")}`),
+      "",
+      dryRun
+        ? "Dry run complete. No files were modified."
+        : "Done. Run the bootstrap prompt to wire to your project.",
+      "",
+    ].join("\n"));
+  } catch (err) {
+    process.stderr.write(`Error: ${err.message}\n`);
+    process.exit(1);
+  }
+
+  process.exit(0);
+}
+
+// ---------------------------------------------------------------------------
+// Default: start MCP server
+// ---------------------------------------------------------------------------
+import("../src/server.js");
+

package/package.json

@@ -1,15 +1,14 @@
 {
   "name": "@oleksandr.rudnychenko/sync_loop",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "description": "MCP server for the SyncLoop agent reasoning protocol — works with Copilot, Cursor, Claude Code",
   "bin": {
-    "sync-loop": "./bin/cli.js"
+    "sync_loop": "./bin/cli.js"
   },
   "files": [
     "bin/",
-    "src/",
-    "template/"
+    "src/"
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",