@dotdotgod/hermes 0.0.0-stage → 0.6.0

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@dotdotgod/hermes",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.0",
+  "description": "Hermes CLI and messaging-gateway adapter without Plan Mode.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Elastic-2.0",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "esbuild": "0.27.3",
+    "@dotdotgod/context": "0.6.0"
+  },
+  "files": [
+    "plugin.yaml",
+    "__init__.py",
+    "runtime.py",
+    "proxy.py",
+    "policy.py",
+    "mcp",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dotdotgod/dotdotgod-kit.git",
+    "directory": "packages/hermes"
+  },
+  "scripts": {
+    "build:runtime": "node ../../scripts/build-adapter-runtime.mjs hermes",
+    "test": "PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -v -s test -p 'test_*.py' && node --test test/*.test.mjs",
+    "verify": "node ../../scripts/build-adapter-runtime.mjs hermes --check && pnpm run test",
+    "pack:dry-run": "pnpm pack --dry-run --json"
+  }
 }

package/plugin.yaml

@@ -0,0 +1,18 @@
+name: dotdotgod
+version: 0.6.0
+description: Project memory, isolated context tools and impact checks for Hermes CLI and messaging gateway; no Plan Mode.
+author: dotdotgod
+license: Elastic-2.0
+config_schema:
+  roots:
+    type: dict
+    default: {}
+    description: Repository labels mapped to absolute local paths, configured by the operator.
+  gateway_access:
+    type: dict
+    default: {}
+    description: 'Allowed repository labels per platform:sender_id principal; no wildcard grants.'
+  cli_root:
+    type: str
+    default: ''
+    description: CLI repository; empty uses the process launch directory.

package/policy.py

@@ -0,0 +1,78 @@
+"""Root-contained changed-file fingerprints and deliberately limited command gates."""
+import hashlib
+import re
+import subprocess
+from pathlib import Path
+
+# ponytail: recognize common release/test invocations, not arbitrary shell/program semantics.
+# Keep host approval/sandbox policy; add a host execution-policy integration if stronger isolation is required.
+GATE = re.compile(r"\bgit\b[^\n;|]{0,200}\b(?:commit|push|tag)\b|\b(?:npm|pnpm|yarn)\b[^\n;|]{0,100}\b(?:publish|deploy|verify|test|build|lint|check)\b|\bpytest\b|\bnode\s+--test\b|\bpython\S*\s+-m\s+unittest\b")
+EXCLUDED = (".dotdotgod/", "node_modules/", "dist/", "build/", "coverage/", "docs/plan/", "docs/archive/")
+
+
+def contained(root, value):
+    path = (root / value).resolve()
+    if not path.is_relative_to(root):
+        raise ValueError("Path escapes selected repository")
+    return path
+
+
+def tracked(path):
+    return not path.startswith(EXCLUDED)
+
+
+def fingerprint(path):
+    try:
+        with path.open("rb") as stream:
+            return hashlib.file_digest(stream, "sha256").hexdigest()
+    except FileNotFoundError:
+        return "missing"
+
+
+def snapshot(root):
+    # ponytail: hash all dirty bytes per gate; cache Git/file signatures only if profiling warrants it.
+    # Dirty and untracked paths only; ignored/local memory is not indexed for impact.
+    names = set()
+    for args in (["diff", "--name-only", "-z", "HEAD"], ["ls-files", "--others", "--exclude-standard", "-z"]):
+        run = subprocess.run(["git", "-C", str(root), *args], capture_output=True, timeout=10)
+        if run.returncode:
+            # A new repository can have no HEAD; fall back to tracked worktree paths.
+            if args[0] == "diff":
+                run = subprocess.run(["git", "-C", str(root), "ls-files", "-z"], capture_output=True, timeout=10)
+            if run.returncode:
+                raise RuntimeError("Impact requires a readable Git worktree; no release commands allowed")
+        names.update(run.stdout.decode("utf-8", errors="strict").split("\0"))
+    return {name: fingerprint(contained(root, name)) for name in sorted(names) if name and tracked(name)}
+
+
+def commands(name, args):
+    if name.endswith("execute"):
+        return [" ".join(str(v) for v in [item.get("command", ""), item.get("executable", ""), *item.get("args", [])])
+                for item in args.get("commands", [])]
+    return [str(args.get(key, "")) for key in ("command", "code", "goal", "tasks", "data")]
+
+
+def gate(name, args, pending):
+    if not pending:
+        return None
+    opaque = name.endswith("execute_file") or (name == "process" and args.get("action") in {"write", "submit"})
+    if opaque or any(GATE.search(text) for text in commands(name, args)):
+        return "Run dotdotgod_project_impact for pending paths before verification/commit/push/publish: " + ", ".join(sorted(pending)[:8])
+    return None
+
+
+def file_arguments(root, name, args):
+    # Hermes file tools use path(s); paths in file patches are still subject to host policy.
+    if name in {"read_file", "write_file", "file_edit", "file_write", "file_read"}:
+        for key in ("path", "file_path"):
+            if isinstance(args.get(key), str):
+                try:
+                    target = contained(root, args[key])
+                except ValueError:
+                    target = Path(args[key]).resolve()
+                    if name not in {"read_file", "file_read"} or not target.is_relative_to(Path(__file__).parent.resolve() / "skills"):
+                        raise
+                args[key] = str(target)
+    if name == "terminal":
+        args["workdir"] = str(contained(root, args.get("workdir") or "."))
+    return args

package/proxy.py

@@ -0,0 +1,95 @@
+"""A serialized stdio bridge per host session. All context processing stays in Node."""
+import json
+import os
+import queue
+import signal
+import subprocess
+import threading
+from pathlib import Path
+
+
+class Proxy:
+    def __init__(self, root, session_id):
+        self.root = str(Path(root).resolve(strict=True))
+        self.session_id = session_id
+        self.lock = threading.RLock()
+        self.process = None
+        self.responses = None
+
+    def _start(self):
+        bridge = Path(__file__).parent / "mcp" / "bridge.mjs"
+        self.process = subprocess.Popen(
+            ["node", str(bridge), self.root, self.session_id], cwd=self.root,
+            stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            text=True, encoding="utf-8", errors="replace", start_new_session=(os.name != "nt"),
+        )
+        responses = self.responses = queue.Queue()
+        process = self.process
+        diagnostic = {"stderr": ""}
+
+        def read_errors():
+            for chunk in iter(lambda: process.stderr.read(1024), ""):
+                diagnostic["stderr"] = (diagnostic["stderr"] + chunk)[-8000:]
+
+        errors = threading.Thread(target=read_errors, daemon=True)
+        errors.start()
+
+        def read():
+            try:
+                for line in process.stdout:
+                    responses.put(json.loads(line))
+            except Exception as error:
+                responses.put({"ok": False, "error": str(error)})
+            finally:
+                errors.join(timeout=0.1)
+                responses.put({"ok": False, "error": "MCP bridge disconnected; call not replayed. " + diagnostic["stderr"]})
+
+        threading.Thread(target=read, daemon=True).start()
+
+    def call(self, name, arguments=None):
+        with self.lock:
+            if self.process is None or self.process.poll() is not None:
+                self.close()
+                self._start()
+            try:
+                request = {"name": name, "arguments": arguments or {}}
+                process, responses = self.process, self.responses
+                process.stdin.write(json.dumps(request) + "\n")
+                process.stdin.flush()
+                response = responses.get(timeout=690)
+                if not response.get("ok"):
+                    raise RuntimeError(response.get("error", "MCP bridge failed"))
+                value = response["value"]
+                if name == "session_resume" and not value.get("isError"):
+                    self.session_id = value["structuredContent"]["sessionId"]
+                return value
+            except Exception:
+                self.close()
+                raise  # Never replay a possibly dispatched mutation.
+
+    def close(self):
+        # Closing is also the explicit cancellation path, so it must not wait for call's lock.
+        process, self.process = self.process, None
+        if process is None:
+            return
+        if process.poll() is None:
+            # Signal the bridge only: it sends MCP cancellation before closing the server.
+            process.terminate()
+            try:
+                process.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                if os.name != "nt":
+                    try:
+                        os.killpg(process.pid, signal.SIGKILL)
+                    except ProcessLookupError:
+                        pass
+                process.kill()
+                process.wait(timeout=2)
+        if os.name != "nt":
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+        for stream in (process.stdin, process.stdout, process.stderr):
+            if stream:
+                stream.close()

package/runtime.py

@@ -0,0 +1,239 @@
+"""Hermes lifecycle routing; shared Node tools retain their wire contracts."""
+import atexit
+import hashlib
+import json
+import re
+import subprocess
+import threading
+from dataclasses import dataclass
+from pathlib import Path
+
+from .policy import contained, file_arguments, gate, snapshot
+from .proxy import Proxy
+
+BASE = Path(__file__).parent
+
+
+def digest(text):
+    return hashlib.sha256(text.encode()).hexdigest()
+
+
+def envelope(data, text=None):
+    return {"content": [{"type": "text", "text": text or json.dumps(data, ensure_ascii=False)}], "structuredContent": data}
+
+
+@dataclass
+class Session:
+    id: str
+    principal: str
+    platform: str
+    root: Path | None = None
+    label: str = ""
+    proxy: Proxy | None = None
+    loaded: bool = False
+    parent_id: str = ""
+
+
+class Runtime:
+    def __init__(self, ctx):
+        self.ctx = ctx
+        self.sessions = {}
+        self.lock = threading.RLock()
+        self.launch_root = Path.cwd().resolve()
+        atexit.register(self.close_all)
+
+    def allowed(self, session):
+        roots = self.ctx.get_config("roots", {})
+        if not isinstance(roots, dict):
+            raise ValueError("roots must be an operator-configured mapping")
+        if session.platform in {"", "cli"}:
+            return roots
+        access = self.ctx.get_config("gateway_access", {})
+        labels = access.get(session.principal, []) if isinstance(access, dict) else []
+        return {label: roots[label] for label in labels if label in roots} if isinstance(labels, list) else {}
+
+    def session(self, session_id):
+        if not session_id or session_id not in self.sessions:
+            raise ValueError("No trusted host session; start a turn before using dotdotgod")
+        session = self.sessions[session_id]
+        if session.root is None:
+            raise ValueError("Select an authorized repository with dotdotgod_select_root first")
+        if session.parent_id:
+            parent = self.session(session.parent_id)
+            if parent.root != session.root or parent.principal != session.principal:
+                raise PermissionError("Delegating parent repository or principal changed")
+        if session.label:
+            value = self.allowed(session).get(session.label)
+            if not isinstance(value, str) or Path(value).resolve(strict=True) != session.root:
+                raise PermissionError("Repository grant changed; select an authorized root again")
+        return session
+
+    def select(self, session, label):
+        if session.parent_id and label != self.session(session.parent_id).label:
+            raise PermissionError("Delegated work cannot select a different repository")
+        value = self.allowed(session).get(label)
+        if not isinstance(value, str) or not Path(value).is_absolute():
+            raise PermissionError("Unknown or unauthorized repository label")
+        root = Path(value).resolve(strict=True)
+        if not root.is_dir():
+            raise ValueError("Repository root must be a directory")
+        if session.proxy:
+            session.proxy.close()
+        session.root, session.label, session.proxy, session.loaded = root, label, None, False
+        self.ctx.state.set("route:" + digest(session.id), {"principal": session.principal, "label": label})
+        return envelope({"ok": True, "root": str(root), "label": label})
+
+    def client(self, session):
+        with self.lock:
+            if session.proxy is None:
+                # Separate connection, but the existing project DB stays shared for the same root.
+                session.proxy = Proxy(session.root, digest(session.principal + "\0" + session.id + "\0" + str(session.root)))
+            return session.proxy
+
+    def pending(self, session):
+        current = snapshot(session.root)
+        checked = self.ctx.state.get("impact:" + digest(str(session.root)), {})
+        return {path: value for path, value in current.items() if checked.get(path) != value}
+
+    def cli(self, session, args):
+        run = subprocess.run(["node", str(BASE / "mcp" / "cli.mjs"), *args], cwd=session.root,
+                             capture_output=True, text=True, timeout=20)
+        if run.returncode:
+            raise RuntimeError((run.stderr or run.stdout or "CLI unavailable")[:1000])
+        return json.loads(run.stdout)
+
+    def load(self, session, args):
+        focus = str(args.get("focus", "")).strip()
+        depth = 3 if focus else 5
+        try:
+            mapping = self.cli(session, ["map", str(session.root), "--depth", str(depth), "--json"])
+        except Exception as error:
+            mapping = {"fallback": [p for p in ["AGENTS.md", "README.md", "docs/README.md"] if (session.root / p).is_file()],
+                       "unavailable": str(error)}
+        query = None
+        if focus:
+            try:
+                query = self.cli(session, ["query", str(session.root), focus, "--limit", "30", "--json"])
+            except Exception as error:
+                query = {"unavailable": str(error), "guidance": "Use map/README routing; do not install embeddings without approval."}
+        session.loaded = True
+        data = {"ok": True, "root": str(session.root), "focus": focus, "documentationMap": mapping, "query": query}
+        return envelope(data, "Project memory (map/query evidence; read bodies selectively):\n" + json.dumps(data, ensure_ascii=False) + "\nHelp: dotdotgod --help")
+
+    def call(self, name, args, session_id):
+        with self.lock:
+            if name == "dotdotgod_select_root":
+                return self.select(self.sessions[session_id], args.get("label"))
+            session = self.session(session_id)
+        if name == "dotdotgod_impact_status":
+            return envelope({"ok": True, "pending": list(self.pending(session))})
+        if name == "dotdotgod_project_load":
+            if contained(session.root, args.get("root") or ".") != session.root:
+                raise ValueError("Use dotdotgod_select_root to change repositories")
+            return self.load(session, args)
+        if name in {"execute", "execute_file"}:
+            reason = self.check(session, name, args)
+            if reason:
+                raise PermissionError(reason)
+        if name == "dotdotgod_project_impact":
+            before = self.pending(session)
+            paths = [contained(session.root, path).relative_to(session.root).as_posix() for path in args.get("paths", [])]
+            args = {**args, "paths": paths}
+        value = self.client(session).call(name, args)
+        if name == "dotdotgod_project_impact" and not value.get("isError") and value.get("structuredContent", {}).get("ok") is True:
+            with self.lock:
+                after = self.pending(session)
+                key = "impact:" + digest(str(session.root))
+                checked = self.ctx.state.get(key, {})
+                for path in paths:
+                    if path in before and before[path] == after.get(path):
+                        checked[path] = before[path]
+                self.ctx.state.set(key, checked)
+        return value
+
+    def check(self, session, name, args):
+        try:
+            pending = self.pending(session)
+        except Exception:
+            pending = {"<impact state unavailable>": "unknown"}
+        return gate(name, args, pending)
+
+    def before_tool(self, tool_name, args, session_id="", **kwargs):
+        try:
+            if tool_name == "dotdotgod_select_root":
+                return None
+            session = self.session(session_id)
+            reason = self.check(session, tool_name, args)
+            if reason:
+                return {"action": "block", "message": reason}
+            rewritten = file_arguments(session.root, tool_name, dict(args))
+            if rewritten != args:
+                return {"action": "modify", "args": rewritten}
+        except Exception as error:
+            return {"action": "block", "message": str(error)}
+
+    def before_llm(self, session_id, user_message, platform="", sender_id="", parent_session_id="", **kwargs):
+        with self.lock:
+            parent = self.session(parent_session_id) if platform == "subagent" else None
+            principal = parent.principal if parent else platform + ":" + sender_id
+            if parent:
+                platform = parent.platform
+            session = self.sessions.get(session_id)
+            if session and session.principal != principal:
+                if session.proxy:
+                    session.proxy.close()
+                session = None
+            if session is None:
+                session = Session(session_id, principal, platform)
+                self.sessions[session_id] = session
+                saved = self.ctx.state.get("route:" + digest(session_id), {})
+                if saved.get("principal") == principal and saved.get("label") in self.allowed(session):
+                    self.select(session, saved["label"])
+                elif parent:
+                    session.root, session.label, session.parent_id = parent.root, parent.label, parent.id
+                elif platform in {"", "cli"}:
+                    session.root = Path(self.ctx.get_config("cli_root", "") or self.launch_root).resolve(strict=True)
+        if session.root is None:
+            return {"context": "Select a repository using dotdotgod_select_root. Authorized labels: " + json.dumps(list(self.allowed(session)))}
+        try:
+            self.session(session_id)
+            parts = []
+            text = user_message if isinstance(user_message, str) else " ".join(p.get("text", "") for p in user_message if isinstance(p, dict))
+            if not session.loaded and not re.search(r"(?:^|\s)/?dd:no-load\b|(?:^|\s)/no-load\b", text):
+                parts.append("Call dotdotgod_project_load once with an agent-selected focus, then continue the original request. Read AGENTS.md and maintained README indexes selectively.")
+            if text.strip():
+                try:
+                    expanded = self.cli(session, ["expand", str(session.root), text, "--json", "--with-impact", "--fuzzy"])
+                    refs = expanded.get("refs", [])
+                    if refs:
+                        parts.append("Reference evidence (non-authoritative): " + json.dumps(refs, ensure_ascii=False))
+                except Exception:
+                    parts.append("Reference expansion unavailable; use README routing and explicit targeted reads.")
+            pending = self.pending(session)
+            if pending:
+                parts.append("Impact pending: " + ", ".join(list(pending)[:8]) + ". Run dotdotgod_project_impact before broad tests or release commands.")
+            return {"context": "\n\n".join(parts)} if parts else None
+        except Exception as error:
+            return {"context": "dotdotgod context unavailable: " + str(error) + "; do not bypass root/impact checks."}
+
+    def finalize(self, session_id="", **kwargs):
+        for child in list(self.sessions.values()):
+            if child.parent_id == session_id:
+                self.finalize(child.id)
+        session = self.sessions.pop(session_id, None)
+        if session and session.proxy:
+            session.proxy.close()
+
+    def end_turn(self, session_id="", interrupted=False, **kwargs):
+        if interrupted:
+            for child in list(self.sessions.values()):
+                if child.parent_id == session_id:
+                    self.end_turn(child.id, interrupted=True)
+            session = self.sessions.get(session_id)
+            if session and session.proxy:
+                session.proxy.close()
+                session.proxy = None
+
+    def close_all(self):
+        for sid in list(self.sessions):
+            self.finalize(sid)

package/skills/document-clarify/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: document-clarify
+description: Document Clarify for dotdotgod project memory in Hermes CLI and messaging gateway.
+---
+
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
+# Document Clarify
+
+Use the operator-authorized selected repository. Prefer the native dotdotgod_project_initialize, dotdotgod_project_load and dotdotgod_project_impact tools for their respective workflows. Context tools use dotdotgod_ names; results contain content and structuredContent, not Pi codemode objects. Do not bypass host permissions or pending impact gates. Hermes native delegate_task handles delegation; this adapter has no Plan Mode.
+
+## Memory-Area Context
+
+Use `dotdotgod config <root> --json` (or the source-checkout CLI equivalent) to obtain resolved `config.areas`; reuse current resolved settings already in context when the project/config has not changed. Normalize the target to a repository-relative path. Check areas in order, applying each area's `excludePaths` before selecting the first matching `paths` entry. Keep the matched area's relevant guidance in context rather than repeatedly injecting the entire configuration. If no area matches, use the document's purpose and repository conventions without inventing metadata.
+
+## Goal
+
+Make project documentation easier to understand and act on while preserving established behavior, decisions, task state, historical meaning, and traceability.
+
+## Editing Checklist
+
+Adapted from [Google Technical Writing One](https://developers.google.com/tech-writing/one); these principles supplement repository policy. Apply them directly without requiring runtime web access.
+
+- **Audience:** distinguish what readers already know from what they need to learn or do. Add only evidence-backed context that closes that gap.
+- **Terminology:** use one consistent name per concept; explain unfamiliar terms and abbreviations when readers need them. Preserve exact API names and identifiers.
+- **Sentences:** use specific verbs and make responsibility clear. Prefer active voice when it helps; retain passive voice when appropriate and never invent an unknown actor. Keep one main idea per sentence while preserving conditions, exceptions, and logical relationships.
+- **Paragraphs:** focus each paragraph on one topic and make its main point clear near the beginning. Remove sentences that do not support that topic or relocate them within the approved scope.
+- **Lists and tables:** use numbered lists when order matters, bullets otherwise, and parallel phrasing for comparable items. Use tables when readers need to compare the same attributes across items, not merely to decorate prose.
+- **Language:** apply these principles idiomatically in the document's language. Do not impose English word order, a passive-voice ban, or sentence-length quotas on Korean or other languages.
+
+## Workflow
+
+1. Confirm the target, audience, requested outcome, and edit scope. Diagnose ambiguity, repetition, or missing information before editing; small changes need no separate diagnostic report. Use matched memory-area metadata when available: `clarify` guidance first, then `description`, `label`, and `role`.
+2. Read only the context needed to preserve meaning: the nearest README, directly linked documents, relevant query results, and targeted history when a past decision matters.
+3. Remove obsolete historical behavior and superseded conditions from current specs when maintained source, tests, or confirmed decisions establish that they no longer apply. Describe current behavior directly rather than narrating how it changed. Do not mistake currently supported compatibility behavior for obsolete history. Preserve current requirements, meaningful limitations, and unresolved uncertainty; when retirement is unverified, ask rather than delete. Preserve historical meaning in archives and reports; do not rewrite past records to look current. Apply criteria suited to the document: README navigation and starting points; spec conditions, behavior, and exceptions; test procedures and pass criteria; architecture boundaries, rationale, and constraints; plan ordering, dependencies, and completion criteria; archive decisions and outcomes in their historical context. Repository-specific guidance takes priority. Clarify terms, ownership, headings, links, and runnable examples. Preserve commands, paths, package/API names, requirement strength, conditions, exceptions, unresolved questions, limitations, and evidence unless verified sources support a change. Do not invent missing facts.
+4. Prefer direct affirmative statements. Remove repeated framing, indirect wording, mixed responsibilities, and irrelevant background. Remove negative or absence statements only when deleting them leaves the reader's understanding, actions, and decisions unchanged. Rewrite redundant contrasts affirmatively: “It is not automatic; the user starts it” becomes “The user starts it.” Preserve meaningful prohibitions, unsupported cases, exceptions, security constraints, and unverified status. Use “X is not Y; it is Z” when the contrast resolves a likely ambiguity. Accuracy takes priority over brevity.
+5. Keep edits within the agreed scope. Confirm scope before splitting or moving files, changing meaning, or editing additional documents outside that scope. Update the nearest README when approved structural changes affect navigation. Follow generated markers and canonical-source instructions. For dotdotgod traceability, edit the fenced `json dotdotgod` block as the canonical mapping. Inspect `dotdotgod traceability links <root> --check --json` before using `--write`; the root-wide write can change unrelated documents, so obtain approval if its affected files exceed the agreed scope. Apply ordinary reference policy: shared documents must not depend on concrete local file paths in inline code or Markdown links; inline-code directory, glob, and placeholder usage examples remain allowed. Preserve traceability's separate stricter local-target prohibition.
+6. Ask for a decision when the requested clarification would change established meaning or when current sources conflict.
+7. Run verification that matches the changed surface. Use documentation and traceability checks for ordinary docs; add generation checks, focused package tests, dry-runs, or workspace verification when shared resources or product behavior are affected. Report briefly: what became clearer; important meaning preserved and unresolved questions; checks run and checks not run. Do not equate shorter text with improved accuracy.
+
+When CLI-backed routing is unavailable, continue from the target document, nearest README, direct links, and repository conventions.

package/skills/impact-review/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: impact-review
+description: Impact Review for dotdotgod project memory in Hermes CLI and messaging gateway.
+---
+
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
+# Impact Review
+
+Use the operator-authorized selected repository. Prefer the native dotdotgod_project_initialize, dotdotgod_project_load and dotdotgod_project_impact tools for their respective workflows. Context tools use dotdotgod_ names; results contain content and structuredContent, not Pi codemode objects. Do not bypass host permissions or pending impact gates. Hermes native delegate_task handles delegation; this adapter has no Plan Mode.
+
+## Goal
+
+Review task-relevant source, config, and documentation changes with dotdotgod impact evidence before broad verification, commits, pushes, publishing, or final handoff. Claude Code and Codex use this advisory workflow; trusted runtime or project hooks may enforce a stricter boundary.
+
+## Workflow
+
+1. Build the changed-file set from Git status. Preserve unrelated user work and exclude dependencies, caches, build output, secrets, and unrelated local memory.
+2. Run one bounded multi-seed impact command for up to 20 unique paths in first-seen order:
+
+   ```bash
+   dotdotgod graph impact <root> --changed <path-a> --changed <path-b> --compact
+   ```
+
+   Use `--yml` when structured detail helps. Split larger sets into ordered batches of 20. In a source checkout, use `node packages/cli/bin/dotdotgod.mjs graph impact`; when the CLI is unavailable, follow README indexes, traceability, package metadata, and focused file search.
+3. Review the combined ranking and each seed's non-seed top results. Prioritize high-signal specs, tests, architecture, and source links, especially `implemented_by`, `verified_by`, and `related_doc` relationships.
+4. Resolve stale or contradictory related docs and tests that belong to the current task.
+5. Select focused tests, documentation validation, generated-resource checks, and package dry-runs from the evidence. For dotdotgod documentation changes, run `dotdotgod validate . --include-local-memory` and add `--check-index` when index freshness matters.
+6. Report the changed files reviewed, the strongest related findings and follow-up actions, and verification completed or skipped.
+
+Keep raw impact payloads out of normal summaries. Optional hooks may remind agents about this workflow; default package resources leave full verification, index rebuilds, initialization, archive moves, and write blocking under explicit workflow control.

package/skills/project-initializer/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: project-initializer
+description: Project Initializer for dotdotgod project memory in Hermes CLI and messaging gateway.
+---
+
+<!-- Generated from packages/shared resources by scripts/generate-adapters.mjs. Do not edit this file directly; edit the shared source and run `pnpm run generate`. -->
+
+# Project Initializer
+
+Use the operator-authorized selected repository. Prefer the native dotdotgod_project_initialize, dotdotgod_project_load and dotdotgod_project_impact tools for their respective workflows. Context tools use dotdotgod_ names; results contain content and structuredContent, not Pi codemode objects. Do not bypass host permissions or pending impact gates. Hermes native delegate_task handles delegation; this adapter has no Plan Mode.
+
+## Goal
+
+Create a non-destructive dotdotgod baseline with canonical agent instructions, thin agent entrypoints, documentation indexes, a project config selected from an appropriate initialization template, and local-memory ignore rules.
+
+## Template Selection
+
+1. Inspect existing agent instructions, the root README, docs indexes, major top-level directories, config, and ignore rules.
+2. Discover custom templates as individual JSON files under `~/.dotdotgod/templates/`. Built-in templates are `software`, `research`, `case-and-evidence`, `publication`, `portfolio`, and `policy`.
+3. Choose from project evidence:
+   - `software`: application, library, or infrastructure projects organized around specs, architecture, source, and tests.
+   - `research`: research diaries, dated records, reports, artifacts, and evaluation evidence.
+   - `case-and-evidence`: canonical case records, evidence or legal grounds, and case outputs.
+   - `publication`: briefs, outlines, chapters, claims, manuscripts, and research sources.
+   - `portfolio`: strategy, positions, ledgers, journals, and market research.
+   - `policy`: policy sections, integrated proposals, evidence, and submission outputs.
+4. Consider custom templates by filename and config contents. A same-name custom template replaces the built-in template completely.
+5. Ask the user when multiple choices are plausible and materially change memory areas or traceability. With insufficient evidence, use `~/.dotdotgod/config.json` `defaultTemplate`, then `software`.
+6. Report the selected template and a concise reason.
+
+## Workflow
+
+1. Preserve existing files and unrelated user work.
+2. Run `dotdotgod init <project-root> [--documentation-root PATH] --template <name>` when available; otherwise run `sh <resolved-skill-directory>/scripts/init_project.sh <project-root> --template <name>`. Existing files must be skipped, not replaced.
+3. The POSIX fallback supports bundled templates only. If a custom template was selected and the CLI is unavailable, stop and explain that custom templates require the CLI; do not silently substitute another template.
+4. Validate the initialized project with `dotdotgod validate <project-root>` when available.
+5. Report created and skipped files, the selected template, validation failures, and unresolved instruction conflicts.

package/skills/project-initializer/references/agent-docs.md

@@ -0,0 +1,41 @@
+# Shared Agent Docs
+
+Use `AGENTS.md` as the canonical shared instruction file.
+
+## Naming
+
+- `AGENTS.md`: preferred shared file name. OpenAI Codex recognizes this convention, and the community `agents.md` convention uses the plural form.
+- `CLAUDE.md`: Claude Code's project memory file. Keep it thin and import `AGENTS.md` with `@AGENTS.md`.
+- `CODEX.md`: project-local Codex pointer. Keep it thin and link to `AGENTS.md`.
+- `.github/copilot-instructions.md`: optional Copilot surface. If present, route to `AGENTS.md`, `docs/README.md`, and project commands instead of copying the full rules body.
+- `.cursor/rules/*.md`: optional Cursor path-scoped rules. If present, keep Cursor-specific scoping there and route durable project rules to shared docs.
+- `llms.txt`: optional documentation discovery surface. If present, point to README indexes and bounded docs entrypoints instead of embedding large docs bodies.
+- `AGENT.md`: avoid for new projects unless an existing tool in the repo requires it.
+
+## Content Model
+
+Put durable, project-wide instructions in `AGENTS.md`:
+
+- project purpose and stack
+- install, test, run, and lint commands
+- architecture and ownership notes
+- documentation map
+- coding and review expectations
+- environment constraints
+
+For projects using the dotdotgod CLI, `dotdotgod validate` is the enforcement point for machine-readable docs rules such as fenced `json dotdotgod` traceability blocks in behavior specs. Keep the detailed schema in the CLI and its validation errors.
+
+Do not duplicate the same body in `CLAUDE.md`, `CODEX.md`, Copilot instructions, Cursor rules, or llms discovery surfaces; duplication causes drift.
+
+## Focused Behavior Contracts
+
+Use focused behavior contracts for user-visible rules that need clear implementation and verification links.
+
+Good focused contracts:
+
+- describe current behavior, not change history
+- stay small enough for agents to load and reason about directly
+- connect to implementation files, tests, related docs, and verification commands with a final fenced `json dotdotgod` traceability block when the project uses dotdotgod validation
+- split large product areas into `docs/spec/<domain>/README.md` plus focused UPPER_SNAKE_CASE spec files
+
+Traceability helps agents find related code and checks. It is not a semantic proof that tests cover every edge case.