@ucsandman/legcli 0.8.0 → 0.10.0

package/src/harness/vendor/agnostic-ai/core/safety/guards.json

@@ -0,0 +1,96 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "version": "2.0.0",
+  "_note": "SINGLE SOURCE OF TRUTH for all safety policy. Consumed read-only by agent/governance/guard.py (Python), engine/hooks/secret-guard.cjs, engine/hooks/dashclaw-guard.cjs (Node), and the dashboard. Do not hardcode policy anywhere else.",
+  "guards": {
+    "secretScan": {
+      "enabled": true,
+      "blockedFiles": [
+        "**/.env",
+        "**/.env.*",
+        "**/.secrets.env",
+        "**/.secrets",
+        "**/id_rsa",
+        "**/id_ed25519",
+        "**/id_ecdsa",
+        "**/id_dsa",
+        "**/*.pem",
+        "**/*.pfx",
+        "**/*.key",
+        "**/*.p12",
+        "**/credentials.json",
+        "**/.aws/credentials",
+        "**/.npmrc",
+        "**/.dashclaw-local/secrets/**"
+      ],
+      "secretPathRegexes": [
+        "(?i)(^|[\\s=\"'`/\\\\(@<>:,*&|;])\\.env(rc)?\\b",
+        "(?i)\\.secrets(\\.env)?\\b",
+        "(?i)\\bid_(rsa|ed25519|ecdsa|dsa)\\b",
+        "(?i)\\.(pem|pfx|p12|key)\\b",
+        "(?i)\\bcredentials\\.json\\b",
+        "(?i)\\.aws[\\\\/]credentials\\b",
+        "(?i)\\.dashclaw-local[\\\\/]secrets"
+      ],
+      "sensitivePatterns": [
+        "(?i)sk_live_[0-9a-zA-Z]{24,}",
+        "(?i)sk-[0-9a-zA-Z]{20,}",
+        "(?i)ghp_[0-9a-zA-Z]{36}",
+        "(?i)gho_[0-9a-zA-Z]{36}",
+        "(?i)xox[baprs]-[0-9a-zA-Z-]{10,}",
+        "(?i)AIza[0-9A-Za-z-_]{35}",
+        "(?i)-----BEGIN [A-Z ]*PRIVATE KEY-----",
+        "(?i)bearer\\s+[a-zA-Z0-9_\\-\\.]{20,}"
+      ]
+    },
+    "processControl": {
+      "protectedProcesses": [
+        "explorer.exe",
+        "system",
+        "powershell.exe",
+        "pwsh.exe",
+        "cmd.exe",
+        "svchost.exe",
+        "claude.exe",
+        "agy.exe",
+        "node.exe"
+      ],
+      "blockedCommands": [
+        "(?i)taskkill.*\\/(im\\s+(explorer|svchost|system)|f)",
+        "(?i)rmdir.*\\/s.*\\/q.*[c-z]:\\\\(windows|users)?$",
+        "(?i)format\\s+[c-z]:"
+      ]
+    },
+    "hardStops": {
+      "_note": "Matched anywhere in the command string; order-independent. These require explicit human approval.",
+      "requireApprovalPatterns": [
+        "(?i)\\bgit\\s+push\\b.*(--force\\b|--force-with-lease\\b|\\s-f\\b)",
+        "(?i)\\bgit\\s+push\\s+-f\\b",
+        "(?i)\\bgit\\s+reset\\s+.*--hard\\b",
+        "(?i)\\bgit\\s+clean\\s+.*-[a-z]*f",
+        "(?i)\\brm\\s+-[a-z]*r[a-z]*f|\\brm\\s+-[a-z]*f[a-z]*r",
+        "(?i)\\brmdir\\s+/s\\b|\\bRemove-Item\\b.*-Recurse",
+        "(?i)\\b(drop\\s+(database|table)|truncate\\s+table)\\b",
+        "(?i)\\bnpm\\s+publish\\b",
+        "(?i)\\bnpm\\s+audit\\s+fix\\s+--force\\b",
+        "(?i)\\bvercel\\s+(--prod|deploy\\s+--prod)\\b",
+        "(?i)\\brailway\\s+up\\b",
+        "(?i)\\brender\\s+deploy\\b",
+        "(?i)\\bstripe\\s+(delete|refund|payout)\\b",
+        "(?i)\\b(deploy|migrate)\\s+(prod|production)\\b"
+      ]
+    },
+    "dashclaw": {
+      "enabled": true,
+      "autoDiscover": true,
+      "defaultRiskThreshold": 50,
+      "hardBlockRiskThreshold": 90,
+      "failClosed": true,
+      "adoptLocalhostPortsAllowed": false,
+      "baseUrl": "https://my-dashclaw.vercel.app",
+      "predictiveRiskEnabled": true,
+      "autoScanBlock": true,
+      "orgHalt": false
+    }
+  }
+}

package/src/harness/vendor/agnostic-ai/core/templates/targets.json

@@ -0,0 +1,252 @@
+{
+  "version": "2.0.0",
+  "_note": "Every AI coding client the harness can be ported to. Field meanings: engine/harness/README.md. Paths are ~-relative; `home` present on disk means the client is installed. Do not hardcode a client path anywhere else.",
+  "targets": [
+    {
+      "id": "claude",
+      "name": "Claude Code",
+      "category": "CLI Agent",
+      "home": "~/.claude",
+      "adapter": "claude",
+      "dialect": "claude",
+      "rulesFile": "~/.claude/agnostic-rules.md",
+      "traitsFile": "~/.claude/SOUL.md",
+      "hooksConfigFile": "~/.claude/settings.json",
+      "skillsDir": "~/.claude/skills",
+      "sharedSkillDirs": [
+        "~/.agents/skills"
+      ],
+      "agentsDir": "~/.claude/agents",
+      "commandsDir": "~/.claude/commands",
+      "mcpConfigFile": "~/.claude.json",
+      "mcpFormat": "mcpServers-json",
+      "preamble": "# Agnostic Rules — Global Working Agreement (Claude Code)\n\nGENERATED by agnostic-ai. Source of truth is the captured harness (or core/rules/). Loaded via an @import line in ~/.claude/CLAUDE.md.\n"
+    },
+    {
+      "id": "codex",
+      "name": "Codex CLI",
+      "category": "CLI Agent",
+      "home": "~/.codex",
+      "adapter": "codex",
+      "dialect": "codex",
+      "rulesFile": "~/.codex/AGENTS.md",
+      "hooksConfigFile": "~/.codex/config.toml",
+      "skillsDir": "~/.codex/skills",
+      "sharedSkillDirs": [
+        "~/.agents/skills"
+      ],
+      "agentsDir": "~/.codex/agents",
+      "commandsDir": "~/.codex/prompts",
+      "mcpConfigFile": "~/.codex/config.toml",
+      "mcpFormat": "codex-toml",
+      "permissionsFile": "~/.codex/rules/agnostic.rules",
+      "preamble": "# AGENTS.md — Global Working Agreement (Codex CLI)\n\nGENERATED by agnostic-ai from the captured harness. Do not hand-edit; edit the source client and run `npm run port`.\n"
+    },
+    {
+      "id": "gemini",
+      "name": "Gemini CLI",
+      "category": "CLI Agent",
+      "home": "~/.gemini",
+      "adapter": "gemini",
+      "dialect": "gemini",
+      "rulesFile": "~/.gemini/GEMINI.md",
+      "traitsFile": "~/.gemini/config/SOUL.md",
+      "hooksConfigFile": "~/.gemini/settings.json",
+      "skillsDir": "~/.gemini/skills",
+      "commandsDir": "~/.gemini/commands",
+      "mcpConfigFile": "~/.gemini/settings.json",
+      "mcpFormat": "mcpServers-json",
+      "preamble": "# GEMINI.md — Global Working Agreement (Gemini CLI)\n\nGENERATED by agnostic-ai from the captured harness. Do not hand-edit; edit the source client and run `npm run port`.\n"
+    },
+    {
+      "id": "agy",
+      "name": "Antigravity CLI",
+      "category": "CLI Agent",
+      "home": "~/.gemini/antigravity-cli",
+      "adapter": "agy",
+      "dialect": "agy",
+      "rulesFile": "~/.gemini/GEMINI.md",
+      "traitsFile": "~/.gemini/config/SOUL.md",
+      "hooksConfigFile": "~/.gemini/config/hooks.json",
+      "skillsDir": "~/.gemini/config/skills",
+      "agentsDir": "~/.gemini/config/agents",
+      "commandsDir": "~/.gemini/config/commands",
+      "mcpConfigFile": "~/.gemini/config/mcp_config.json",
+      "mcpFormat": "mcpServers-json",
+      "preamble": "# GEMINI.md — Global Working Agreement (Gemini CLI)\n\nGENERATED by agnostic-ai from the captured harness. Do not hand-edit; edit the source client and run `npm run port`.\n"
+    },
+    {
+      "id": "cursor",
+      "name": "Cursor",
+      "category": "Agentic IDE",
+      "home": "~/.cursor",
+      "adapter": "cursor",
+      "dialect": "cursor",
+      "rulesFile": "~/.cursor/rules/global-rules.mdc",
+      "hooksConfigFile": "~/.cursor/hooks.json",
+      "skillsDir": "~/.cursor/skills",
+      "agentsDir": "~/.cursor/agents",
+      "commandsDir": "~/.cursor/commands",
+      "mcpConfigFile": "~/.cursor/mcp.json",
+      "mcpFormat": "mcpServers-json",
+      "preamble": "---\ndescription: \"Global Working Agreement and safety rules\"\nglobs: \"*\"\nalwaysApply: true\n---\n\n# Cursor Rules — Global Working Agreement\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "windsurf",
+      "name": "Windsurf (Cascade)",
+      "category": "Agentic IDE",
+      "home": "~/.windsurf",
+      "dialect": "windsurf",
+      "rulesFile": "~/.windsurf/rules/global-rules.md",
+      "skillsDir": "~/.windsurf/skills",
+      "mcpConfigFile": "~/.codeium/windsurf/mcp_config.json",
+      "mcpFormat": "mcpServers-json",
+      "preamble": "# Windsurf Rules — Global Working Agreement\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "copilot",
+      "name": "GitHub Copilot",
+      "category": "VS Code Extension",
+      "home": "~/.copilot",
+      "dialect": "copilot",
+      "rulesFile": "~/.github/copilot-instructions.md",
+      "skillsDir": "~/.copilot/skills",
+      "preamble": "# GitHub Copilot Global Instructions\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "cline",
+      "name": "Cline",
+      "category": "VS Code Extension",
+      "home": "~/.cline",
+      "dialect": "cline",
+      "rulesFile": "~/.cline/prompts/global-rules.md",
+      "skillsDir": "~/.cline/skills",
+      "mcpConfigFile": "~/.cline/cline_mcp_settings.json",
+      "mcpFormat": "mcpServers-json",
+      "preamble": "# Cline — Global Working Agreement\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "aider",
+      "name": "Aider",
+      "category": "CLI Agent",
+      "home": "~/.aider",
+      "dialect": "aider",
+      "rulesFile": "~/.aider.conventions.md",
+      "preamble": "# Aider — Conventions & Global Working Agreement\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "openhands",
+      "name": "OpenHands",
+      "category": "Autonomous Agent",
+      "home": "~/.openhands",
+      "dialect": "openhands",
+      "rulesFile": "~/.openhands/AGENTS.md",
+      "skillsDir": "~/.openhands/skills",
+      "sharedSkillDirs": [
+        "~/.agents/skills"
+      ],
+      "preamble": "# AGENTS.md — OpenHands Global Agreement\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "goose",
+      "name": "Goose (Block)",
+      "category": "Autonomous Agent",
+      "home": "~/.config/goose",
+      "dialect": "goose",
+      "rulesFile": "~/.config/goose/.goosehints",
+      "skillsDir": "~/.config/goose/skills",
+      "preamble": "# .goosehints — Goose Global System Hints\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "continue",
+      "name": "Continue.dev",
+      "category": "VS Code Extension",
+      "home": "~/.continue",
+      "dialect": "continue",
+      "rulesFile": "~/.continue/rules/global-rules.md",
+      "skillsDir": "~/.continue/skills",
+      "preamble": "# Continue.dev — Global Agent Rules\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "zed",
+      "name": "Zed AI",
+      "category": "Agentic IDE",
+      "home": "~/.config/zed",
+      "dialect": "zed",
+      "rulesFile": "~/.config/zed/AGENTS.md",
+      "preamble": "# AGENTS.md — Zed AI Global Instructions\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "opencode",
+      "name": "OpenCode",
+      "category": "CLI Agent",
+      "home": "~/.config/opencode",
+      "dialect": "opencode",
+      "rulesFile": "~/.config/opencode/AGENTS.md",
+      "skillsDir": "~/.config/opencode/skills",
+      "sharedSkillDirs": [
+        "~/.agents/skills"
+      ],
+      "commandsDir": "~/.config/opencode/commands",
+      "mcpConfigFile": "~/.config/opencode/opencode.json",
+      "mcpFormat": "opencode-json",
+      "preamble": "# AGENTS.md — OpenCode Global Instructions\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "trae",
+      "name": "Trae (ByteDance)",
+      "category": "Agentic IDE",
+      "home": "~/.trae",
+      "dialect": "trae",
+      "rulesFile": "~/.trae/user_rules/user_rules.md",
+      "skillsDir": "~/.trae/skills",
+      "preamble": "# user_rules.md — Trae User Rules\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "amazonq",
+      "name": "Amazon Q Developer",
+      "category": "Enterprise Assistant",
+      "home": "~/.amazonq",
+      "dialect": "amazonq",
+      "rulesFile": "~/.amazonq/rules/global-rules.md",
+      "preamble": "# Amazon Q Developer — Global Rules\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "cody",
+      "name": "Sourcegraph Cody",
+      "category": "Enterprise Assistant",
+      "home": "~/.sourcegraph",
+      "dialect": "cody",
+      "rulesFile": "~/.sourcegraph/rules/global-rules.rule.md",
+      "preamble": "# Sourcegraph Cody — Global Rules\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "openclaw",
+      "name": "OpenClaw",
+      "category": "Autonomous Agent",
+      "home": "~/.openclaw",
+      "dialect": "openclaw",
+      "rulesFile": "~/.openclaw/SYSTEM.md",
+      "skillsDir": "~/.openclaw/skills",
+      "preamble": "# SYSTEM.md — OpenClaw Agent System Prompt\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "hermes",
+      "name": "Hermes Agent",
+      "category": "Autonomous Agent",
+      "home": "~/.hermes",
+      "dialect": "hermes",
+      "rulesFile": "~/.hermes/agent_system.md",
+      "skillsDir": "~/.hermes/skills",
+      "preamble": "# agent_system.md — Hermes System Prompt\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    },
+    {
+      "id": "generic",
+      "name": "Generic LLM System Card",
+      "category": "Local / API",
+      "dialect": "generic",
+      "rulesFile": "storage/compiled/system_prompt.md",
+      "preamble": "# System Prompt for Autonomous LLM Agents\n\nGENERATED by agnostic-ai from the captured harness.\n"
+    }
+  ]
+}

package/src/harness/vendor/agnostic-ai/engine/harness/README.md

@@ -0,0 +1,199 @@
+# engine/harness — the port engine
+
+One harness, captured from the client you actually use, applied to every other
+client so it behaves the same. This directory is the contract every adapter is
+written against. Read it before adding a source or a target.
+
+```
+capture (sources/<client>.cjs)  ->  harness/ bundle  ->  apply (targets/<client>.cjs)
+```
+
+- `capture.cjs`  reads the live config of ONE client (the *source*) into the
+  client-neutral bundle under `<repo>/harness/`.
+- `apply.cjs`    renders the bundle into every other installed client (the
+  *targets*), one guarded write per file, and records what it dropped and why.
+- `status.cjs`   reads every target from disk and reports, per component, whether
+  it is in sync. Nothing here is asserted from memory.
+- `cli.cjs`      `capture | apply | port | status | explain`.
+- `index.cjs`    the engine as a library: the entry a host product requires (see
+  "Embedding" below).
+- `bundle.cjs`   load / save / validate the bundle; secret scan.
+- `common.cjs`   shared helpers (paths, guarded writes, links, managed regions,
+  frontmatter, TOML strings).
+
+## Embedding
+
+A host product (Leg, github.com/ucsandman/legcli, is the first) runs this
+directory as a library and owns everything around it. Nothing in the engine
+reads a repo file when the host passes the equivalent:
+
+```js
+const engine = require('agnostic-ai/engine/harness/index.cjs');
+engine.configure({
+  brand: { id: 'host', mark: 'GENERATED by Host', region: 'host' }, // the ownership claim in every generated file
+  secretPatterns: [/* regexes; replaces core/safety/guards.json */],
+  shimPath: '/abs/path/to/the/hook/shim',                            // what non-Codex hooks point at
+  importRoots: [],                                                    // dirs besides home an @import may resolve into
+});
+const registry = engine.loadRegistry(home, { targets: myTargets });   // replaces core/templates/targets.json
+const port = { ...myPolicy, baseDir: myDir };                         // replaces core/port.json; addenda resolve against baseDir
+const { bundle, warnings } = engine.capture({ from: 'claude', home, outDir, registry, port });
+const report = engine.apply({ bundle, home, registry, port, storageDir, to: ['codex'] });
+engine.status({ bundle, home, registry, port, storageDir });
+```
+
+`bundle.fingerprint(b)` is a content hash of everything a target renders from
+(the manifest's timestamp excluded); `save()` records it in
+`manifest.fingerprint`, so a host can answer "did the harness change since the
+last apply" without diffing files. `common.GENERATED_MARK` is a live getter
+over the configured brand. Node's ESM loader imports `index.cjs` directly.
+Regression: `engine/tests/reg-harness.cjs` section 10.
+
+## The bundle (`<repo>/harness/`)
+
+Client-neutral, human-readable, gitignored by default (it holds machine paths).
+The Claude Code dialect is the canonical one for hooks and tool names because
+Codex adopted a near-clone of it and every other client is mapped from it.
+
+| File | Shape |
+|---|---|
+| `manifest.json` | `{ version, source, sourceHome, capturedAt, components: {rules, hooks, skills, agents, commands, mcp, permissions} }` (counts) |
+| `rules.md` | The global working agreement with every `@import` inlined and the source client's own header stripped. Plain markdown, no client name in the prose that the port can avoid. |
+| `identity.md` | Optional. SOUL.md / traits. |
+| `hooks.json` | `{ "dialect": "claude", "events": { "<Event>": [ { "matcher"?: "A\|B", "hooks": [ { "type": "command", "command": "...", "timeout"?: 10, "statusMessage"?: "...", "async"?: false } ] } ] } }`. Events and matcher tokens use Claude Code names (`PreToolUse`, `Bash`, `Edit`, ...). |
+| `mcp.json` | `{ "servers": { "<name>": { "transport": "stdio" \| "http" \| "sse", "command"?, "args"?: [], "env"?: {K: V}, "cwd"?, "url"?, "headers"?: {} } } }`. A secret-looking env value is replaced at capture by `"${NAME}"` and reported; targets render that as "read NAME from the environment". |
+| `agents/<name>.md` | Frontmatter `name`, `description`, `model` (`fable` \| `opus` \| `sonnet` \| `haiku` \| `inherit` \| raw id), `tools` (comma list, Claude names), `readonly` (`true` when no edit tool is listed); body = the agent's instructions. |
+| `commands/<name>.md` | Frontmatter `description`, `argument-hint`; body = the prompt. |
+| `skills.json` | `{ "sourceDir": "<abs>", "skills": [ { "name", "path": "<abs dir with SKILL.md>" } ] }`. Skills are never copied: targets link each one, so an edit at the source is live everywhere. |
+| `permissions.json` | `{ "allow": [...], "deny": [...], "ask": [...] }` in Claude pattern syntax (`Bash(git *)`). Targets map what they can and drop the rest with a reason. |
+
+`bundle.cjs` validates the shape and refuses to save a bundle that carries a
+value matching `core/safety/guards.json -> sensitivePatterns`.
+
+## `core/port.json`
+
+The user-editable port policy (tracked; a template user commits their own):
+
+```jsonc
+{
+  "source": "auto",              // "auto" | "claude" | "codex"
+  "targets": "installed",        // "installed" | "all" | ["codex", "gemini"]
+  "rules": { "dropSectionsForTargets": ["Delegation and Model Routing"] },
+  "hooks": {
+    "exclude": [ { "match": "<regex on the command>", "reason": "..." } ],
+    "extra": { "<targetId>": { "<Event>": [ <group> ] } }   // target-only hooks appended after the ported ones
+  },
+  "skills": { "exclude": { "<name>": "reason" } },
+  "mcp":    { "exclude": { "<name>": "reason" } },
+  "agents": { "modelLadder": { "<targetId>": { "fable": ["<model>", "<effort>"], "opus": [...], "sonnet": [...], "haiku": [...] } } }
+}
+```
+
+## Target registry (`core/templates/targets.json`)
+
+Every client is one entry. Paths are `~`-relative and expanded with
+`common.expandPath`. Presence of `home` on disk means "installed".
+
+| Field | Meaning |
+|---|---|
+| `id`, `name`, `category` | identity |
+| `home` | the client's config dir; absent on disk = not installed = skipped by `"targets": "installed"` |
+| `adapter` | which `targets/<adapter>.cjs` renders it (`generic` when omitted) |
+| `rulesFile`, `preamble`, `traitsFile` | rules surface (every target has one) |
+| `hooksConfigFile` | hook config the adapter manages (omit = client has no hooks) |
+| `skillsDir`, `sharedSkillDirs` | where skills are linked; dirs the client already reads natively (a skill living there is not linked twice) |
+| `agentsDir`, `commandsDir` | subagent and slash-command surfaces |
+| `mcpConfigFile`, `mcpFormat` | MCP surface; `mcpFormat` is `mcpServers-json` (Claude/Cursor/Windsurf/Cline/Gemini shape), `codex-toml`, `opencode-json` |
+| `dialect` | hook payload dialect for `engine/hooks/shim.cjs` (`claude`, `codex`, `gemini`, `agy`, `cursor`) |
+
+## Adapter contract
+
+### `sources/<id>.cjs`
+
+```js
+module.exports = {
+  id: 'claude',
+  // Returns { bundle, warnings: [string] }. Never throws on a missing optional
+  // surface (no agents dir = zero agents). Throws only when the rules file is missing.
+  capture({ home, target, port }) {}
+};
+```
+
+`bundle` is the in-memory shape of the directory above: `{ manifest, rules,
+identity, hooks, mcp, agents: [{name, meta, body}], commands: [{name, meta,
+body}], skills, permissions }`. Use `bundle.createBundle()` to get an empty one.
+
+### `targets/<id>.cjs`
+
+```js
+module.exports = {
+  id: 'codex',
+  components: ['rules', 'identity', 'hooks', 'skills', 'agents', 'commands', 'mcp', 'permissions'],
+  rules(ctx) {}, identity(ctx) {}, hooks(ctx) {}, skills(ctx) {}, agents(ctx) {}, commands(ctx) {}, mcp(ctx) {}, permissions(ctx) {}
+};
+```
+
+Every component function receives the same `ctx`:
+
+| Field | What |
+|---|---|
+| `target` | the registry entry with every path already expanded to an absolute path |
+| `bundle` | the loaded bundle |
+| `port` | `core/port.json` |
+| `home` | home dir being written (tests pass a temp dir; production passes `os.homedir()`) |
+| `check` | true = report only, write nothing |
+| `dryRun` | true = print what would change, write nothing (same as check but verbose) |
+| `force` | true = overwrite hand-edited files |
+| `state` | mutable object persisted to `storage/harness-state.json`; use `ctx.state.files[path] = sha` via `ctx.write` and `ctx.state.owned[targetId]` for links / entries the adapter created so it can prune them later |
+| `backup(path)` | copy a file into the backups dir before an adapter prunes it; returns the backup path |
+| `write(path, content, opts)` | the guarded writer: backs up, refuses hand edits unless `force`, honours `check`; returns `{ action: 'written' \| 'unchanged' \| 'would-write' \| 'skipped-hand-edited', backup }` |
+| `link(src, dest)` | junction / symlink one directory; returns `{ action }`; never replaces a real directory |
+| `log(line)` | human line for the CLI |
+
+And returns a `ComponentResult`:
+
+```js
+{
+  status: 'synced' | 'written' | 'stale' | 'skipped' | 'unsupported' | 'error',
+  files: [ { path, action } ],           // every file touched or inspected
+  dropped: [ { item, reason } ],         // what was NOT ported and why (shown by `explain`)
+  note: 'one line for the status table', // optional
+  error: 'message'                        // when status === 'error'
+}
+```
+
+Rules for every adapter:
+
+1. **One writer per file.** A file the adapter manages carries
+   `GENERATED by agnostic-ai` within its first five lines (the preamble; a
+   title line may come first) or a marked region
+   `# >>> agnostic-ai <component> start` / `# <<< agnostic-ai <component> end`
+   (files the user also edits, like `config.toml` and `settings.json` arrays).
+   Everything outside the region is preserved byte for byte.
+2. **Idempotent.** A second run with no source change writes nothing and
+   `--check` exits 0. Regions are rebuilt deterministically.
+3. **Never destroy user content.** `ctx.write` backs up before overwriting and
+   refuses a hand-edited file without `force`; links never replace a real
+   directory; prune only what `ctx.state.owned` says we created.
+4. **Every drop is explained.** A hook, skill, agent or server that cannot be
+   ported lands in `dropped` with a reason a stranger understands.
+5. **Facts come from disk.** A model id, a hook trust hash, a skill list is read
+   from the target's own files, never asserted from memory. Where a hash scheme
+   is reproduced (Codex hook trust), keep a self-test against a value the client
+   itself wrote.
+6. **Secrets never move.** An env value that looks like a token is written as an
+   environment reference, and the user is told which variable to export.
+
+## Hook dialect shim (`engine/hooks/shim.cjs`)
+
+Hooks are written once, in the Claude Code dialect (JSON on stdin, decision on
+stdout / exit 2). Clients that speak another dialect run them through the shim:
+
+```
+node engine/hooks/shim.cjs --client cursor --event preToolUse -- node ~/.claude/hooks/rm-guard.cjs ++ node ~/.claude/hooks/scope-lock.cjs
+```
+
+The shim translates the incoming payload to the Claude shape, runs each command
+in the chain (first deny wins), and translates the decision back. Fail-open: a
+crashed guard or unparseable payload yields "no opinion", never a deny that wedges
+the client. Codex needs no shim.