@bcelep/capint 0.6.5 → 0.7.0

package/docs/generated/ui-api.v1.md

@@ -0,0 +1,178 @@
+# CapInt UI Wizard API
+
+> Auto-generated from `schemas/ui-api.v1.json`. Do not edit by hand.
+
+**$id:** `https://capint.dev/schemas/ui-api.v1.json`
+
+## Properties
+
+| Field | Type | Required |
+|-------|------|----------|
+
+## Raw schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://capint.dev/schemas/ui-api.v1.json",
+  "title": "CapInt UI Wizard API",
+  "definitions": {
+    "RouteRequest": {
+      "type": "object",
+      "required": [
+        "task"
+      ],
+      "properties": {
+        "task": {
+          "type": "string",
+          "minLength": 1
+        },
+        "locale": {
+          "enum": [
+            "tr",
+            "en"
+          ]
+        }
+      }
+    },
+    "RouteResponse": {
+      "type": "object",
+      "required": [
+        "result",
+        "text_report",
+        "chat_copy"
+      ],
+      "properties": {
+        "result": {
+          "type": "object",
+          "required": [
+            "execution_intent"
+          ],
+          "properties": {
+            "execution_intent": {
+              "$ref": "execution-intent.v1.json"
+            }
+          }
+        },
+        "text_report": {
+          "type": "string"
+        },
+        "chat_copy": {
+          "type": "string"
+        }
+      }
+    },
+    "HealthResponse": {
+      "type": "object",
+      "required": [
+        "ok",
+        "doctor",
+        "status"
+      ],
+      "properties": {
+        "ok": {
+          "type": "boolean"
+        },
+        "doctor": {
+          "type": "object"
+        },
+        "status": {
+          "type": "object",
+          "properties": {
+            "skills_on_disk": {
+              "type": "number"
+            },
+            "core_skills": {
+              "type": "number"
+            },
+            "matrix_version": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "capint_package": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "RecoverRequest": {
+      "type": "object",
+      "properties": {
+        "apply": {
+          "type": "boolean",
+          "default": false
+        },
+        "latest": {
+          "type": "boolean",
+          "default": true
+        }
+      }
+    },
+    "FeedbackRequest": {
+      "type": "object",
+      "properties": {
+        "rating": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 5
+        },
+        "comment": {
+          "type": "string",
+          "maxLength": 2000
+        },
+        "source": {
+          "type": "string",
+          "default": "ui"
+        }
+      }
+    }
+  },
+  "paths": {
+    "/api/health": {
+      "get": {
+        "response": {
+          "$ref": "#/definitions/HealthResponse"
+        }
+      }
+    },
+    "/api/route": {
+      "post": {
+        "request": {
+          "$ref": "#/definitions/RouteRequest"
+        },
+        "response": {
+          "$ref": "#/definitions/RouteResponse"
+        }
+      }
+    },
+    "/api/recover": {
+      "post": {
+        "request": {
+          "$ref": "#/definitions/RecoverRequest"
+        },
+        "response": {
+          "type": "object"
+        }
+      }
+    },
+    "/api/feedback": {
+      "post": {
+        "request": {
+          "$ref": "#/definitions/FeedbackRequest"
+        },
+        "response": {
+          "type": "object",
+          "properties": {
+            "ok": {
+              "type": "boolean"
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```

package/docs/maintainer-dogfood.md

@@ -29,7 +29,7 @@ node bin/capint.js ide sync --targets cursor,claude,gemini,antigravity
 npm link             # global `capint` → bu repo
 ```
 
-Meta: [`.capint/context.json`](../.capint/context.json) · Oturum: [HANDOFF.md](../HANDOFF.md)
+Meta: [`.capint/context.json`](../.capint/context.json) · Oturum: [HANDOFF.md](../HANDOFF.md) · Tamamlanan: [DONE.md](../DONE.md)
 
 ---
 
@@ -46,7 +46,8 @@ npm run release-check
 node bin/capint.js route --json "debug login"
 ```
 
-Chat: [GUNLUK.md](../GUNLUK.md) — terminal zorunlu değil; route/doctor debug içindir.
+Chat: [GUNLUK.md](../GUNLUK.md) — terminal zorunlu değil; route/doctor debug içindir.  
+Kapanış: `kapan` → agent `DONE.md` + `HANDOFF.md` günceller.
 
 ---
 

package/docs/recipes/memory-graph-pairing.md

@@ -0,0 +1,200 @@
+# Memory & graph pairing (CapInt + sidecars)
+
+> **Tek giriş:** [capint-stack.md](../capint-stack.md) — ANWS workflows + graphify + agentmemory + init.  
+> Bu dosya katman 3–4 detay/recipe.
+
+CapInt **routes and gates** memory/graph usage. It does **not** embed MemPalace, agentmemory, or graphify. Use this recipe to wire optional sidecars.
+
+**Architecture:** [architecture-decisions.md](../architecture-decisions.md) — adapters only, default off.
+
+---
+
+## Roles
+
+| Tool | Role | CapInt integration |
+|------|------|-------------------|
+| **CapInt local** | HANDOFF, AGENT, design, `context_pack` | Always (Tier 0) |
+| **[graphify](https://github.com/safishamsi/graphify)** | Folder → `GRAPH_REPORT.md` + `graph.json` | File contract (Tier 1) |
+| **[agentmemory](https://github.com/rohitg00/agentmemory)** | Session memory MCP server | Sidecar health (Tier 2) |
+| **[MemPalace](https://github.com/MemPalace/mempalace)** | Python palace + MCP (optional alt) | Optional probe (Tier 3) |
+
+CapInt decides **when** (`memory-retrieval`, `CAPINT_MEMORY`, `CAPINT_GRAPH`). Sidecars provide **how**.
+
+---
+
+## Tier 0 — Local (no install)
+
+Works today without extra tools.
+
+```bash
+capint route "memory lookup geçen karar"
+# Agent reads HANDOFF.md + context-memory-bridge skill
+```
+
+Optional hot-path file search on route:
+
+```powershell
+$env:CAPINT_LOCAL_CONTEXT="1"
+capint route --json "memory lookup geçen karar"
+# execution_intent.local_adapters populated when flag set
+```
+
+**Check:** `capint providers doctor`
+
+---
+
+## Tier 1 — graphify (file producer)
+
+1. Install graphify (PyPI package name may be `graphifyy`):
+
+   ```bash
+   pipx install graphifyy
+   graphify install   # skill into Claude/Cursor host
+   ```
+
+2. Build graph once per repo (or on major changes):
+
+   ```bash
+   graphify .
+   # or: graphify ./src --update
+   ```
+
+3. Point CapInt at outputs (pick one layout):
+
+   **A — repo root (CapInt default paths)**
+
+   ```text
+   GRAPH_REPORT.md
+   .capint/graph/graph.json
+   ```
+
+   Copy or symlink from `graphify-out/`:
+
+   ```powershell
+   Copy-Item graphify-out/GRAPH_REPORT.md .
+   New-Item -ItemType Directory -Force .capint/graph
+   Copy-Item graphify-out/graph.json .capint/graph/graph.json
+   ```
+
+   **B — custom paths via `.capint/providers.json`**
+
+   ```json
+   {
+     "graph": {
+       "driver": "local",
+       "paths": ["graphify-out/GRAPH_REPORT.md", "graphify-out/graph.json"]
+     }
+   }
+   ```
+
+4. Enable local adapters:
+
+   ```powershell
+   $env:CAPINT_LOCAL_CONTEXT="1"
+   capint providers doctor
+   capint route --json "explain auth module dependencies"
+   ```
+
+CapInt never runs graphify — it only reads artifacts.
+
+---
+
+## Tier 2 — agentmemory (MCP sidecar)
+
+1. Install and start server:
+
+   ```bash
+   npm install -g @agentmemory/agentmemory
+   agentmemory          # listens on :3111 by default
+   ```
+
+2. Wire Cursor (or your IDE):
+
+   ```bash
+   agentmemory connect cursor
+   ```
+
+3. CapInt activation (when route needs memory providers):
+
+   ```powershell
+   $env:CAPINT_MEMORY="1"
+   # optional remote:
+   # $env:AGENTMEMORY_URL="http://localhost:3111"
+   capint route --json "memory lookup geçen karar"
+   ```
+
+4. Verify sidecar:
+
+   ```bash
+   capint providers doctor --json
+   curl http://localhost:3111/agentmemory/health
+   ```
+
+**Do not** duplicate agentmemory hooks inside CapInt — let agentmemory capture sessions; CapInt gates routing.
+
+**Pairs with graphify:** agentmemory remembers sessions; graphify structures the codebase. See agentmemory [pairings doc](https://github.com/rohitg00/agentmemory/blob/main/docs/recipes/pairings.md).
+
+---
+
+## Tier 3 — MemPalace (optional Python alt)
+
+For Python-first teams already using the palace:
+
+```bash
+uv tool install mempalace
+mempalace init ~/projects/myapp
+mempalace mine ~/.claude/projects/ --mode convos
+```
+
+Use MemPalace MCP in the IDE separately. CapInt v0.7.x only **probes** CLI presence in `providers doctor`; full MCP adapter is backlog (0.8.0).
+
+**Security:** Official sources only — [github.com/MemPalace/mempalace](https://github.com/MemPalace/mempalace) and [pypi.org/project/mempalace](https://pypi.org/project/mempalace/). Ignore impostor domains.
+
+---
+
+## Env reference
+
+| Variable | Effect |
+|----------|--------|
+| `CAPINT_LOCAL_CONTEXT=1` | Attach `local_adapters` on route (file search + graph excerpts) |
+| `CAPINT_MEMORY=1` | Allow memory provider activation (stub until 0.8 adapter) |
+| `CAPINT_GRAPH=1` | Allow graph provider activation |
+| `AGENTMEMORY_URL` | agentmemory server base URL (default `http://localhost:3111`) |
+
+Matrix policy: providers default **off** until capability requires memory or flags set — see `provider_activation_policy` in `skill-routing-matrix.json`.
+
+---
+
+## Recommended stack (Cursor + CapInt)
+
+```text
+1. capint init / dogfood maintainer repo
+2. graphify .  → copy outputs to GRAPH_REPORT.md + .capint/graph/graph.json
+3. agentmemory (background) + agentmemory connect cursor
+4. CAPINT_LOCAL_CONTEXT=1 for file adapters on route
+5. capint providers doctor  → green Tier 0 + 1; Tier 2 if server up
+6. Chat via GUNLUK / capint ui — memory-retrieval tasks route to context-memory-bridge
+```
+
+---
+
+## Roadmap (CapInt)
+
+| Version | Deliverable |
+|---------|-------------|
+| **0.7.x** | This recipe + `capint providers doctor` |
+| **0.8.0** | Real `MemoryProvider` / `GraphProvider` adapters (HTTP/MCP delegate, not stubs) |
+| **0.8.x** | `capint providers.json` template in init; optional `--with-memory-recipe` doc link |
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `provider_activation.activated: true` but empty results | Stubs in 0.7.x — use Tier 0/1 file paths or wait for 0.8 adapter |
+| Graph excerpts always 0 | Run graphify; ensure `GRAPH_REPORT.md` or `graph.json` exists |
+| agentmemory unreachable | Start server; check `AGENTMEMORY_URL` |
+| Duplicate capture hooks | Use agentmemory OR IDE hooks, not both blindly |
+
+**Diagnostic:** `capint providers doctor [--json]`

package/docs/skill-audit-runbook.md

@@ -0,0 +1,32 @@
+# Skill audit runbook (maintainer)
+
+Quarterly checklist for registry bloat and orphan skills.
+
+## Commands
+
+```bash
+npm run skill-audit          # JSON report, exit 1 on issue-tier findings
+capint skill audit           # human-readable
+capint audit --json          # includes skill audit + doctor + contract drift
+```
+
+## Finding codes
+
+| Code | Meaning | Action |
+|------|---------|--------|
+| `orphan_on_disk` | `skills/X/SKILL.md` not in registry | `capint skill pin X` or remove folder |
+| `registry_ghost` | Registry entry missing on disk | Re-init bundle or remove from registry |
+| `matrix_unreferenced` | Optional skill unused in matrix | Archive candidate (info only) |
+| `stale_backup` | Backup older than 90 days | Prune `.capint/backups/` after review |
+
+## Quarterly loop
+
+1. Run `capint skill audit --json` on maintainer repo and one dogfood project.
+2. Triage `issue` findings first (core ghosts).
+3. Batch `orphan_on_disk` → pin project-specific skills or delete experiments.
+4. Document decisions in CHANGELOG if registry tiers change.
+5. Re-run `npm test` before publish.
+
+## Out of scope (0.7.0)
+
+`--archive` dry-run only in docs; physical archive moves planned for 0.7.1.

package/locales/en.json

@@ -0,0 +1,27 @@
+{
+  "ui.subtitle": "No terminal — write your task, review the plan, copy to chat.",
+  "ui.step.project": "Project",
+  "ui.step.task": "Task",
+  "ui.step.plan": "Plan",
+  "ui.step.chat": "Chat",
+  "ui.health.check": "Check",
+  "ui.health.checking": "Checking…",
+  "ui.health.ok": "✓ Doctor: OK",
+  "ui.health.fail": "✗ Doctor: issues found",
+  "ui.tooltip.installed": "installed = SKILL.md exists under skills/. It does not need to appear in the IDE skill picker.",
+  "ui.plan.why": "Why",
+  "ui.plan.technical": "Technical detail",
+  "ui.recover.fix": "Suggested fix",
+  "ui.recover.apply": "Fix now",
+  "ui.recover.confirm": "Restore from the latest backup?",
+  "ui.feedback.title": "Was this flow helpful?",
+  "ui.feedback.submit": "Send feedback",
+  "ui.faq.link": "FAQ / user guide",
+  "term.capability": "Capability",
+  "term.resolution": "Resolution",
+  "term.prd": "PRD = product requirements document",
+  "term.installed": "Skill installed on disk (skills/…/SKILL.md)",
+  "doctor.summary.registry": "Registry or matrix looks broken; you can restore from the latest backup.",
+  "doctor.summary.disabled": "A core skill is disabled; you can re-enable it.",
+  "doctor.summary.ok": "Project configuration looks healthy."
+}

package/locales/tr.json

@@ -0,0 +1,27 @@
+{
+  "ui.subtitle": "Terminal yok — görevini yaz, planı gör, chat'e kopyala.",
+  "ui.step.project": "Proje",
+  "ui.step.task": "Görev",
+  "ui.step.plan": "Plan",
+  "ui.step.chat": "Chat",
+  "ui.health.check": "Kontrol et",
+  "ui.health.checking": "Kontrol ediliyor…",
+  "ui.health.ok": "✓ Doctor: OK",
+  "ui.health.fail": "✗ Doctor: sorun var",
+  "ui.tooltip.installed": "installed = skills/ klasöründe SKILL.md var. Cursor skill listesinde görünmesi gerekmez.",
+  "ui.plan.why": "Neden",
+  "ui.plan.technical": "Teknik detay",
+  "ui.recover.fix": "Önerilen düzeltme",
+  "ui.recover.apply": "Düzelt",
+  "ui.recover.confirm": "Son yedeği geri yüklemek istiyor musun?",
+  "ui.feedback.title": "Bu akış işine yaradı mı?",
+  "ui.feedback.submit": "Geri bildirim gönder",
+  "ui.faq.link": "SSS / kullanım kılavuzu",
+  "term.capability": "Capability",
+  "term.resolution": "Resolution",
+  "term.prd": "PRD = ürün gereksinim belgesi",
+  "term.installed": "Skill diskte yüklü (skills/…/SKILL.md)",
+  "doctor.summary.registry": "Registry veya matrix bozuk görünüyor; son yedekten geri yükleyebilirsin.",
+  "doctor.summary.disabled": "Bir core skill kapalı; yeniden açabilirsin.",
+  "doctor.summary.ok": "Proje yapılandırması sağlıklı görünüyor."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bcelep/capint",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Capability-first orchestration engine for IDE agents",
   "license": "MIT",
   "bin": {
@@ -18,6 +18,7 @@
     "skill-routing-matrix.json",
     "registry.json",
     "schemas/",
+    "locales/",
     "ui/",
     "README.md",
     "CHANGELOG.md",
@@ -30,7 +31,8 @@
     "test:unit": "node tests/contract-snapshot.test.mjs",
     "test:e2e": "node tests/ui-wizard.e2e.mjs",
     "validate": "node scripts/validate-matrix.mjs",
-    "release-check": "node scripts/release-check.mjs"
+    "release-check": "node scripts/release-check.mjs",
+    "skill-audit": "node bin/capint.js skill audit --json"
   },
   "devDependencies": {
     "ajv": "^8.17.1",

package/projections/session-start.md

@@ -8,7 +8,7 @@ description: "CapInt session start + Execution Intent — projected via capint i
 
 Every **new conversation**, before editing files:
 
-1. Read root `GUNLUK.md` (daily use) + `AGENT.md` + `design.md` (+ `HANDOFF.md` if present).
+1. Read root `GUNLUK.md` (daily use) + `AGENT.md` + `design.md` (+ `HANDOFF.md` if present). Skim `DONE.md` if scope might repeat past work.
 2. Read `skills/prismx-skill-gateway/SKILL.md` before medium+ code edits.
 3. Keep startup output short (2–5 lines).
 
@@ -23,7 +23,7 @@ When the user assigns work:
    - `Resolution: provider/resource`
    - `Memory: none|optional|required`
    - `Plan: auto|confirm|override`
-3. **Explanation Card (medium+):** before apply, show up to 8 lines — why, task type, keywords, files to read (`explanation` block or `capint route --verbose`).
+3. **Explanation Card (medium+):** before apply, show up to 8 lines — **`reason_plain` first** (business language), then technical `reason_summary`; task type, keywords, files to read (`explanation` block or `capint route --verbose`).
 4. **Confirm (adaptive):** light → apply after Intent (`Plan: auto`); medium/heavy → one short Turkish question — accept devam/plan/analiz (tokens optional):
    - devam / yap / evet → apply
    - plan / planla / önce plan → short plan first
@@ -35,6 +35,18 @@ When the user assigns work:
 # Paths
 
 - Session: `AGENT.md`
+- Active handoff: `HANDOFF.md` (if present)
+- Completed log: `DONE.md` (append-only)
 - Gateway: `skills/prismx-skill-gateway/SKILL.md`
 - Matrix: `skill-routing-matrix.json`
 - CLI preview: `capint route "<task>"`
+
+# Session end
+
+When the user closes a session (`kapan`, `oturumu bitir`, `HANDOFF güncelle`, `DONE kaydet`):
+
+1. **Append** one row to `DONE.md` — date, short summary, verification (e.g. `npm test`, `capint doctor`).
+2. **Rewrite** `HANDOFF.md` — where we left off, next 3 steps, blockers (active context only).
+3. If code changed: note whether `npm test` / release-check was green.
+4. Keep startup output short; do not duplicate full chat history in either file.
+

package/schemas/execution-intent.v1.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://capint.dev/schemas/execution-intent.v1.json",
+  "title": "CapInt Execution Intent",
+  "type": "object",
+  "required": [
+    "intent",
+    "capability",
+    "resolution",
+    "memory",
+    "plan",
+    "confirm",
+    "confirm_question",
+    "confirm_options",
+    "confirm_default_option",
+    "fallback"
+  ],
+  "properties": {
+    "intent": { "type": "string" },
+    "capability": { "type": "string" },
+    "resolution": { "type": "string" },
+    "memory": { "enum": ["none", "optional", "required"] },
+    "plan": { "enum": ["auto", "confirm", "override"] },
+    "confirm": {
+      "type": "object",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "mode": { "type": "string" },
+        "prompt": { "type": ["string", "null"] },
+        "options": { "type": "array" },
+        "default_option": { "type": ["string", "null"] }
+      }
+    },
+    "confirm_question": { "type": ["string", "null"] },
+    "confirm_options": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "label"],
+        "properties": {
+          "id": { "type": "string" },
+          "label": { "type": "string" }
+        }
+      }
+    },
+    "confirm_default_option": { "type": ["string", "null"] },
+    "fallback": { "type": ["object", "null"] },
+    "verification_required": { "type": "boolean" },
+    "verification_hints": { "type": "array", "items": { "type": "string" } },
+    "verification_profile": { "type": "string" },
+    "route_explain": { "type": "object" },
+    "explanation": { "$ref": "explanation.v2.json" },
+    "provider_activation": { "type": ["object", "null"] },
+    "context_pack": { "type": ["object", "null"] },
+    "orchestration": { "type": ["object", "null"] },
+    "resolution_status": { "type": "string" },
+    "resolution_hint": { "type": "string" },
+    "workspace_boundary": {
+      "type": "object",
+      "properties": {
+        "violated": { "type": "boolean" },
+        "suspicious_paths": { "type": "array", "items": { "type": "string" } },
+        "override_hint": { "type": ["string", "null"] }
+      }
+    },
+    "overlay_error": { "type": "string" },
+    "local_adapters": { "type": "object" }
+  }
+}

package/schemas/explanation.v2.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://capint.dev/schemas/explanation.v2.json",
+  "title": "CapInt Route Explanation v2",
+  "type": "object",
+  "required": [
+    "task_type_id",
+    "matched_keywords",
+    "winner",
+    "files_to_read",
+    "reason_summary",
+    "alternatives_considered"
+  ],
+  "properties": {
+    "task_type_id": { "type": ["string", "null"] },
+    "matched_keywords": { "type": "array", "items": { "type": "string" } },
+    "winner": {
+      "type": ["object", "null"],
+      "properties": {
+        "type": { "type": "string" },
+        "resource": { "type": "string" }
+      }
+    },
+    "files_to_read": { "type": "array", "items": { "type": "string" } },
+    "reason_summary": { "type": "string" },
+    "reason_plain": { "type": "string" },
+    "tooltip": { "type": "string" },
+    "locale": { "enum": ["tr", "en"] },
+    "alternatives_considered": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "resource": { "type": "string" },
+          "type": { "type": "string" },
+          "confidence": { "type": ["number", "null"] }
+        }
+      }
+    },
+    "resolver_order": { "type": "array", "items": { "type": "string" } },
+    "files_intended": { "type": "array", "items": { "type": "string" } },
+    "workspace_boundary": {
+      "type": "object",
+      "properties": {
+        "violated": { "type": "boolean" },
+        "suspicious_paths": { "type": "array", "items": { "type": "string" } },
+        "override_hint": { "type": ["string", "null"] }
+      }
+    }
+  }
+}