delimit-cli 4.7.1 → 4.7.3

package/CHANGELOG.md

@@ -1,6 +1,43 @@
 # Changelog
 
 
+## [4.7.3] - 2026-06-04
+
+Docs + metadata release. No functional changes to the package.
+
+### Changed
+
+- npm README now carries the **"Adopt with minimum privilege"** section
+  (phase-1 read-only tool allowlist, Action SHA-pinning, BYOK vault guidance)
+  that previously only rendered on GitHub.
+- Detection-engine claims corrected to **28 change types (17 breaking,
+  11 non-breaking)** — adds `field_requirement_relaxed` (context-aware
+  severity) to the documented table.
+- `server.json` (MCP registry metadata) version brought current.
+
+
+## [4.7.2] - 2026-06-04
+
+### Fixed
+
+- **Tool-usage telemetry now persists.** `record_call` previously only kept an
+  in-memory per-session counter that vanished on restart, so tool utilization
+  was unobservable. It now appends every call to `~/.delimit/tool_usage.jsonl`
+  (crash-safe, append-only), making utilization and dormancy measurable.
+
+### Added
+
+- **`delimit_toolcard_cache action="usage"`** — durable tool-utilization +
+  dormancy report (per-tool call counts, `last_seen`, and registered tools never
+  called).
+- Additive next-step suggestions wiring under-surfaced tools into the governance
+  loop: `lint → impact`, `agent_dispatch → agent_link`, `deploy_verify →
+  seal_verify`, `evidence_collect → seal_verify`, `os_plan → os_gates`.
+
+Purely additive — no tool signature or behavior changed. Published via OIDC
+trusted publishing with provenance.
+
+
 ## [4.7.1] - 2026-06-03
 
 Release-infrastructure update. No functional changes to the package versus 4.7.0.

package/README.md

@@ -226,6 +226,40 @@ That's it. Delimit auto-fetches the base branch spec, diffs it, and posts a PR c
 
 ---
 
+## Adopt with minimum privilege
+
+You don't have to trust a large tool surface on day one. The safe on-ramp:
+
+**Phase 1 — read-only governance (free, no account).** Start with the tools that
+only read your repo and write reports: `delimit_lint`, `delimit_diff`,
+`delimit_semver`, `delimit_policy`, `delimit_explain`, `delimit_scan`, and
+`delimit_seal_verify`. If your MCP client supports per-tool allowlists, grant
+exactly those. Nothing in this set executes, deploys, or posts anywhere.
+
+**Phase 2 — opt into side effects deliberately.** Tools that write evidence
+bundles, open PR comments, or run deploys (`delimit_security_audit`,
+`delimit_deploy_*`, agent orchestration) are tier-gated; enable them once
+phase 1 has earned its keep in your CI.
+
+**Pin the Action to a commit SHA.** `@v1` is a floating tag. For
+supply-chain-sensitive pipelines, pin the exact commit and bump on review:
+
+```yaml
+- uses: delimit-ai/delimit-action@<commit-sha>   # gh api repos/delimit-ai/delimit-action/git/refs/tags/v1
+```
+
+**Keep BYOK keys out of plaintext config.** If you bring your own model keys
+for deliberation, store them with `delimit_secret_store` (encrypted vault,
+access-logged via `delimit_secret_access_log`) rather than in dotfiles.
+
+Our own releases ship under the same discipline: every release carries a
+signed, replayable Seal receipt (see the latest
+[release assets](https://github.com/delimit-ai/delimit-mcp-server/releases) —
+verify with `npx delimit-cli seal-verify <receipt.json>` or at its
+`delimit.ai/att/<id>` replay URL), plus SLSA provenance on npm.
+
+---
+
 ## CLI commands
 
 ```bash
@@ -290,7 +324,7 @@ When installed into your AI coding assistant, Delimit provides tools across two
 
 ## What It Detects
 
-27 change types (17 breaking, 10 non-breaking) -- deterministic rules, not AI inference. Same input always produces the same result.
+28 change types (17 breaking, 11 non-breaking) -- deterministic rules, not AI inference. Same input always produces the same result.
 
 ### Breaking Changes
 
@@ -328,6 +362,7 @@ When installed into your AI coding assistant, Delimit provides tools across two
 | 25 | `security_added` | API key security scheme added |
 | 26 | `deprecated_added` | `GET /v1/users` marked as deprecated |
 | 27 | `default_changed` | Default value for `page_size` changed from 10 to 20 |
+| 28 | `field_requirement_relaxed` | Required field `nickname` became optional (context-aware severity) |
 
 ---
 
@@ -367,7 +402,7 @@ rules:
 
 **How does this compare to Obsidian Mind?**
 
-Obsidian Mind is a great Obsidian vault template for Claude Code users who want persistent memory via markdown files. Delimit takes a different approach: it's an MCP server that works across Claude Code, Codex, Gemini CLI, and Cursor. Your memory, ledger, and governance travel with you when you switch models. Delimit also adds API governance (27-type breaking change detection), CI gates, git hooks, and policy enforcement that Obsidian Mind doesn't cover. Use Obsidian Mind if you're all-in on Claude + Obsidian. Use Delimit if you switch between models or need governance.
+Obsidian Mind is a great Obsidian vault template for Claude Code users who want persistent memory via markdown files. Delimit takes a different approach: it's an MCP server that works across Claude Code, Codex, Gemini CLI, and Cursor. Your memory, ledger, and governance travel with you when you switch models. Delimit also adds API governance (28-type breaking change detection), CI gates, git hooks, and policy enforcement that Obsidian Mind doesn't cover. Use Obsidian Mind if you're all-in on Claude + Obsidian. Use Delimit if you switch between models or need governance.
 
 **Does this work without Claude Code?**
 

package/gateway/ai/server.py

@@ -742,6 +742,7 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
     "lint": [
         {"tool": "delimit_explain", "reason": "Get migration guide for breaking changes", "suggested_args": {"template": "migration"}, "is_premium": False},
         {"tool": "delimit_semver", "reason": "Determine the version bump for these changes", "suggested_args": {}, "is_premium": False},
+        {"tool": "delimit_impact", "reason": "Enumerate downstream callers affected by a breaking change before it ships", "suggested_args": {}, "is_premium": True},
     ],
     "diff": [
         {"tool": "delimit_semver", "reason": "Classify the semver bump for these changes", "suggested_args": {}, "is_premium": False},
@@ -766,7 +767,9 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
         {"tool": "delimit_diagnose", "reason": "Check environment and tool status", "suggested_args": {}, "is_premium": False},
     ],
     # --- Tier 2 Platform (Pro) ---
-    "os_plan": [],
+    "os_plan": [
+        {"tool": "delimit_os_gates", "reason": "Check whether the new OS plan passes its governance gates", "suggested_args": {}, "is_premium": True},
+    ],
     "os_status": [],
     "os_gates": [],
     "gov_health": [
@@ -799,6 +802,7 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
     # --- Agent Orchestration (Pro) ---
     "agent_dispatch": [
         {"tool": "delimit_agent_status", "reason": "Check the status of your dispatched task", "suggested_args": {}, "is_premium": True},
+        {"tool": "delimit_agent_link", "reason": "Link this dispatched task to its ledger item for the replay/audit trail (operating-model mandate)", "suggested_args": {}, "is_premium": True},
     ],
     "agent_status": [
         {"tool": "delimit_agent_complete", "reason": "Mark a task as complete when done", "suggested_args": {}, "is_premium": True},
@@ -871,6 +875,10 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
     "deploy_publish": [
         {"tool": "delimit_deploy_verify", "reason": "Verify deployment health after publish", "suggested_args": {}, "is_premium": True},
     ],
+    "deploy_verify": [
+        {"tool": "delimit_evidence_collect", "reason": "Collect a deploy evidence bundle", "suggested_args": {}, "is_premium": True},
+        {"tool": "delimit_seal_verify", "reason": "Verify the signed, replayable attestation produced by the deploy", "suggested_args": {}, "is_premium": False},
+    ],
     "deploy_rollback": [],
     "deploy_status": [],
     "generate_template": [],
@@ -880,9 +888,13 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
     ],
     "evidence_collect": [
         {"tool": "delimit_evidence_verify", "reason": "Verify evidence bundle integrity", "suggested_args": {}, "is_premium": True},
+        {"tool": "delimit_seal_verify", "reason": "Verify the Seal attestation receipt (Ed25519 + content-pin) for this artifact", "suggested_args": {}, "is_premium": False},
     ],
     "evidence_verify": [],
-    "seal_verify": [],
+    "seal_verify": [
+        {"tool": "delimit_evidence_collect", "reason": "Collect an evidence bundle for the verified attestation", "suggested_args": {}, "is_premium": True},
+        {"tool": "delimit_notify", "reason": "Notify stakeholders that the merge attestation verified", "suggested_args": {}, "is_premium": True},
+    ],
     "security_audit": [
         {"tool": "delimit_security_scan", "reason": "Run deeper security scan on flagged areas", "suggested_args": {}, "is_premium": True},
         {"tool": "delimit_evidence_collect", "reason": "Collect evidence of security findings", "suggested_args": {}, "is_premium": True},
@@ -13235,7 +13247,7 @@ def delimit_loop_config(session_id: Annotated[str, Field(description="Session to
 
 @mcp.tool()
 def delimit_toolcard_cache(
-    action: Annotated[str, Field(description="One of \"status\" (default), \"register\", \"delta\", \"clear\", \"estimate\", \"flush\".")] = "status",
+    action: Annotated[str, Field(description="One of \"status\" (default), \"register\", \"delta\", \"clear\", \"estimate\", \"flush\", \"usage\" (durable tool utilization + dormancy report).")] = "status",
     tool_schemas: Annotated[Optional[str], Field(description="JSON array of tool schema objects (for register/ estimate).")] = None,
     tool_names: Annotated[Optional[str], Field(description="Comma-separated tool names (for delta).")] = None,
 ) -> Dict[str, Any]:
@@ -13255,13 +13267,16 @@ def delimit_toolcard_cache(
 
     Args:
         action: One of "status" (default), "register", "delta",
-            "clear", "estimate", "flush".
+            "clear", "estimate", "flush", "usage". "usage" returns the
+            durable tool-utilization + dormancy report (per-tool call
+            counts, last_seen, and registry tools never called).
         tool_schemas: JSON array of tool schema objects (for register/
             estimate).
         tool_names: Comma-separated tool names (for delta).
 
     Returns:
-        Dict with the action result (stats, delta names, estimate, etc).
+        Dict with the action result (stats, delta names, estimate,
+        usage/dormancy summary, etc).
     """
     from ai.license import require_premium
     gate = require_premium("toolcard_cache")
@@ -13306,8 +13321,26 @@ def delimit_toolcard_cache(
         r = cache.estimate_savings(schemas)
     elif action == "flush":
         r = cache.flush_session()
+    elif action == "usage":
+        # Durable tool utilization / dormancy report. record_call now persists
+        # every call to ~/.delimit/tool_usage.jsonl; usage_summary aggregates
+        # counts + last_seen and, given the registered-tool list, flags tools
+        # never called as `dormant`. Mechanizes the dormant-tool audit.
+        registry = None
+        try:
+            tm = getattr(mcp, "_tool_manager", None)
+            if tm is not None:
+                if hasattr(tm, "list_tools"):
+                    registry = [getattr(t, "name", None) or t.get("name") for t in tm.list_tools()]
+                elif hasattr(tm, "_tools"):
+                    registry = list(tm._tools.keys())
+            if registry:
+                registry = sorted(n for n in registry if n)
+        except Exception:
+            registry = None
+        r = cache.usage_summary(registry=registry)
     else:
-        r = {"error": "unknown_action", "message": f"Unknown action: {action}. Use: status, register, delta, clear, estimate, flush"}
+        r = {"error": "unknown_action", "message": f"Unknown action: {action}. Use: status, register, delta, clear, estimate, flush, usage"}
 
     return _with_next_steps("toolcard_cache", r)
 

package/gateway/ai/toolcard_cache.py

@@ -209,8 +209,71 @@ class ToolcardCache:
         }
 
     def record_call(self, tool_name: str) -> None:
-        """Record that a tool was called in the current session."""
+        """Record that a tool was called: in-memory (session) AND durably.
+
+        The prior implementation only kept an in-memory counter that vanished on
+        process restart, so tool utilization was never observable across sessions
+        (usage.json stayed empty and dormancy was unmeasurable). We now also
+        append to a crash-safe, append-only JSONL event log so utilization is
+        measurable over time. Append is O(1) with no read-modify-write race.
+        Analytics must never break a tool call, so all failures are swallowed.
+        """
         self._session_calls[tool_name] = self._session_calls.get(tool_name, 0) + 1
+        try:
+            usage_log = self._cache_file.parent / "tool_usage.jsonl"
+            usage_log.parent.mkdir(parents=True, exist_ok=True)
+            with open(usage_log, "a") as f:
+                f.write(json.dumps({
+                    "ts": datetime.now(timezone.utc).isoformat(),
+                    "tool": tool_name,
+                }) + "\n")
+        except Exception:
+            pass
+
+    def usage_summary(self, registry: Optional[List[str]] = None) -> Dict[str, Any]:
+        """Aggregate the durable usage log into per-tool counts + dormancy.
+
+        Reads tool_usage.jsonl (written by record_call). When `registry` (the
+        full list of registered tool names) is provided, tools that appear in
+        the registry but never in the log are reported as `dormant`.
+        """
+        usage_log = self._cache_file.parent / "tool_usage.jsonl"
+        counts: Dict[str, int] = {}
+        last_seen: Dict[str, str] = {}
+        total = 0
+        try:
+            with open(usage_log, "r") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        rec = json.loads(line)
+                    except Exception:
+                        continue
+                    name = rec.get("tool")
+                    if not name:
+                        continue
+                    counts[name] = counts.get(name, 0) + 1
+                    ts = rec.get("ts")
+                    if ts and (name not in last_seen or ts > last_seen[name]):
+                        last_seen[name] = ts
+                    total += 1
+        except FileNotFoundError:
+            pass
+        result: Dict[str, Any] = {
+            "total_calls": total,
+            "distinct_tools_used": len(counts),
+            "counts": dict(sorted(counts.items(), key=lambda x: x[1], reverse=True)),
+            "last_seen": last_seen,
+            "usage_log": str(usage_log),
+        }
+        if registry is not None:
+            used = set(counts)
+            result["registry_size"] = len(registry)
+            result["dormant"] = sorted(t for t in registry if t not in used)
+            result["dormant_count"] = len(result["dormant"])
+        return result
 
     def get_stats(self) -> Dict[str, Any]:
         """Return cache stats: total tools, cached, cache hit rate, token savings."""

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "delimit-cli",
   "mcpName": "io.github.delimit-ai/delimit-mcp-server",
-  "version": "4.7.1",
+  "version": "4.7.3",
   "description": "Unify Claude Code, Codex, Cursor, and Gemini CLI with persistent context, governance, and multi-model debate.",
   "main": "index.js",
   "files": [

package/server.json

@@ -7,13 +7,13 @@
     "url": "https://github.com/delimit-ai/delimit-mcp-server",
     "source": "github"
   },
-  "version": "4.5.13",
+  "version": "4.7.3",
   "websiteUrl": "https://delimit.ai",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "delimit-cli",
-      "version": "4.5.13",
+      "version": "4.7.3",
       "transport": {
         "type": "stdio"
       }