From 85dd488892c20b9e3bc6bcf0886cf2be5bf71007 Mon Sep 17 00:00:00 2001
From: phungthien269 <phungthien269@users.noreply.github.com>
Date: Fri, 2 Oct 2026 00:17:22 +0700
Subject: [PATCH 1/3] feat: add DeepSeek Harness guide, hooks generator, and
 setup skill

- docs/DEEPSEEK-HARNESS-GUIDE.md: skills roots, hooks bridge mounting, loader rules learned from practice, scope table | - scripts/dsh/generate-hooks-config.js: convert hooks/hooks.json to the dsh-hooks-claude-code bridge format (lower-case tool matchers, inline plugin-root env prefix, timeout preserved, unsupported events skipped) | - skills/deepseek-harness-setup: skills-first entry point per repo policy | - tests/scripts/dsh-generate-hooks-config.test.js: 8 unit + CLI tests
---
 docs/DEEPSEEK-HARNESS-GUIDE.md                | 128 +++++++++++++++
 scripts/dsh/generate-hooks-config.js          | 154 ++++++++++++++++++
 skills/deepseek-harness-setup/SKILL.md        |  79 +++++++++
 .../scripts/dsh-generate-hooks-config.test.js | 104 ++++++++++++
 4 files changed, 465 insertions(+)
 create mode 100644 docs/DEEPSEEK-HARNESS-GUIDE.md
 create mode 100644 scripts/dsh/generate-hooks-config.js
 create mode 100644 skills/deepseek-harness-setup/SKILL.md
 create mode 100644 tests/scripts/dsh-generate-hooks-config.test.js

diff --git a/docs/DEEPSEEK-HARNESS-GUIDE.md b/docs/DEEPSEEK-HARNESS-GUIDE.md
new file mode 100644
index 000000000..8d62c15fb
--- /dev/null
+++ b/docs/DEEPSEEK-HARNESS-GUIDE.md
@@ -0,0 +1,128 @@
+# DeepSeek Harness Guide
+
+ECC runs on the [DeepSeek Harness](https://github.com/deepseek-ai/dsh) (DSH) via its
+native skill roots and the first-party Claude Code hooks bridge. This guide covers
+what works out of the box, how to mount the ECC hooks, and the current limits.
+
+Unlike the Qwen or Codex adapters, there is no dedicated installer target yet; the
+setup is a small amount of manual configuration described below.
+
+## Prerequisites
+
+- DeepSeek Harness 0.2.0-rc.1 or newer (`dsh --version`).
+- ECC repository cloned locally, for example `~/ECC` (the hooks bridge commands
+  reference this path, so keep the checkout in place).
+- Skills need no extra tooling; hooks use the `@deepseek-ai/dsh-hooks-claude-code`
+  plugin that ships inside the DSH runtime itself.
+
+## Skills (automatic)
+
+DSH loads skills from these roots (earlier roots win on name conflicts):
+
+```text
+<project>/.dsh/skills
+<project>/.agents/skills
+custom dirs (~/.dsh/profiles/<profile>/cordis.patch.yml -> skill-filesystem)
+~/.dsh/skills
+~/.agents/skills
+```
+
+Because ECC already ships `.agents/skills/` for Codex, opening a session with the
+ECC checkout as the working directory exposes a subset of ECC skills immediately.
+To expose the full curated set in every project, link the catalog once:
+
+```bash
+ln -s /path/to/ECC/skills/<skill-name> ~/.dsh/skills/<skill-name>
+```
+
+DSH reads `SKILL.md` frontmatter (name/description), which matches the ECC skill
+format, so no conversion is needed. Name conflicts with pre-existing user skills
+are resolved by root priority; skip those skills when linking.
+
+## Hooks
+
+### How the bridge works
+
+DSH bridges ECC command hooks through `@deepseek-ai/dsh-hooks-claude-code`
+(first-party, bundled with the runtime). Constraints that shape the conversion:
+
+- Supported events: `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
+  `PostToolUse`, `Stop`, `SubagentStart`, `SubagentStop`. ECC events without a
+  bridge counterpart (`PreCompact`, `PostToolUseFailure`, `SessionEnd`) are
+  skipped by the generator.
+- DSH tool names are lower-case (`bash`, `edit`, `write`, `skill`, `task`),
+  while ECC matchers use Claude Code names (`Bash`, `Edit|MultiEdit`, ...). The
+  generator maps known tool names and keeps regex passthrough tokens.
+- The bridge runs commands with `bash -c` and does not export the plugin root as
+  an environment variable for hook processes. The generator prefixes each command
+  with `CLAUDE_PLUGIN_ROOT=<ecc-root> ECC_PLUGIN_ROOT=<ecc-root>` (env-prefix
+  form), which the ECC hook bootstrap reads at startup.
+- `timeout` values are seconds in both formats and are preserved.
+
+### Generate the config
+
+```bash
+node scripts/dsh/generate-hooks-config.js --ecc-root /path/to/ECC --out ~/.dsh/ecc/hooks-dsh.json
+```
+
+The script validates nothing about your DSH install; it only converts
+`hooks/hooks.json` into the bridge format and prints what it skipped.
+
+### Mount into a profile
+
+Add a bare insert entry to the profile patch layer
+(`~/.dsh/profiles/<profile>/cordis.patch.yml`). This mirrors how the bundled web
+app preset mounts its plugins:
+
+```yaml
+- insert:
+    - id: ecc-hooks-claude-code
+      name: "@deepseek-ai/dsh-hooks-claude-code"
+      config:
+        configPath: /absolute/path/to/hooks-dsh.json
+```
+
+Configuration notes from practice:
+
+- A plain top-level entry (`- id: ...`) is silently dropped; the loader only
+  treats `insert` entries as additions.
+- `insert` under an existing non-group id is rejected ("not a group"); use a bare
+  insert without a target id.
+- The plugin package does not need to be added to the profile `package.json`;
+  first-party plugins resolve from the DSH runtime install.
+- Validate without booting: `cd ~/.dsh && dsh --profile <profile> --dump-config`
+  (compose errors and dropped entries are reported on stderr).
+
+### Verify
+
+```bash
+# Compose check (no session boot)
+cd ~/.dsh && dsh --profile web --dump-config > /dev/null && echo OK
+
+# End-to-end: fire a SessionStart hook in a one-shot headless session
+# (uses a test config with a single marker-writing hook)
+dsh --profile headless --patch /tmp/ecc-patch-test.yml 'Reply with exactly: BOOT-OK'
+```
+
+In a live web session, the GateGuard fact-forcing hook denies the first
+edit/write/bash attempt until facts are presented — a visible signal that the
+bridge is active.
+
+## Updating
+
+```bash
+cd /path/to/ECC && git pull
+node scripts/dsh/generate-hooks-config.js --ecc-root /path/to/ECC --out ~/.dsh/ecc/hooks-dsh.json
+```
+
+Linked skills reflect the pull immediately (symlinks), only the hooks config
+needs regeneration.
+
+## Scope
+
+| Surface | Status on DSH |
+|---------|---------------|
+| Skills (293) | Works; link or rely on `.agents/skills` |
+| Hooks (20 command hooks, 4 of 7 events) | Works via the bridge; 3 events unsupported |
+| Commands (94 slash commands) | Not available (Claude Code mechanism); workflows are covered by skills |
+| Agents (68) | Not available as subagents; equivalent personas exist as skills |
diff --git a/scripts/dsh/generate-hooks-config.js b/scripts/dsh/generate-hooks-config.js
new file mode 100644
index 000000000..f66b82570
--- /dev/null
+++ b/scripts/dsh/generate-hooks-config.js
@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * Generate a DeepSeek Harness (DSH) hooks config from hooks/hooks.json.
+ *
+ * DSH bridges ECC command hooks through the first-party plugin
+ * @deepseek-ai/dsh-hooks-claude-code. The bridge supports a subset of
+ * Claude Code hook events and lower-cases tool names in matchers, so this
+ * script converts the canonical ECC hooks.json into a DSH-compatible file.
+ *
+ * Usage:
+ *   node scripts/dsh/generate-hooks-config.js [--ecc-root <dir>] [--out <file>]
+ *
+ * Defaults:
+ *   --ecc-root  directory of this checkout (repo root)
+ *   --out       <ecc-root>/hooks/hooks.dsh.json
+ *
+ * The output is a Claude Code hooks-format file consumed by the bridge:
+ *   { "hooks": { "PreToolUse": [ { "matcher": "...", "hooks": [...] } ] } }
+ *
+ * Unsupported ECC events (no DSH bridge counterpart) are skipped and
+ * reported on stderr: PreCompact, PostToolUseFailure, SessionEnd.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SUPPORTED_EVENTS = new Set([
+  'SessionStart', 'UserPromptSubmit', 'PreToolUse', 'PostToolUse', 'Stop',
+  'SubagentStart', 'SubagentStop',
+]);
+
+// Claude Code tool names -> DSH lower-case tool names used by the bridge.
+const TOOL_NAME_MAP = {
+  Bash: 'bash',
+  PowerShell: 'powershell',
+  Write: 'write',
+  Edit: 'edit',
+  MultiEdit: 'edit',
+  Skill: 'skill',
+  Task: 'task',
+};
+
+function parseArgs(argv) {
+  const opts = { eccRoot: null, out: null };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--ecc-root') opts.eccRoot = argv[++i];
+    else if (a === '--out') opts.out = argv[++i];
+    else {
+      process.stderr.write('Unknown argument: ' + a + '\n');
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+/**
+ * Map a Claude Code matcher expression to DSH tool-name tokens.
+ * Split on |, map known tool names to lower-case DSH names, keep regex
+ * passthrough tokens (like .* or ^mcp__) untouched, de-duplicate.
+ */
+function mapMatcher(matcher) {
+  if (typeof matcher !== 'string' || matcher.length === 0) return matcher;
+  const parts = matcher.split('|').map(function (t) {
+    const v = t.trim();
+    if (v === '' || v === '.*' || v === '^mcp__') return v;
+    const mapped = TOOL_NAME_MAP[v];
+    return mapped !== undefined ? mapped : v.toLowerCase();
+  });
+  return Array.from(new Set(parts)).join('|');
+}
+
+/**
+ * Rewrite an ECC command into a DSH bridge command.
+ *
+ * The bridge runs commands with bash -c but does not export the plugin
+ * root as an environment variable for every hook process. Each ECC hook
+ * command embeds a resolver (`node -e "..." <hook-id> <script> [args]`)
+ * that resolves scripts/hooks/plugin-hook-bootstrap.js from the
+ * CLAUDE_PLUGIN_ROOT environment variable, so prefixing the variables
+ * inline (env-prefix form) is the only required change.
+ */
+function mapCommand(command, eccRoot) {
+  const prefix = 'CLAUDE_PLUGIN_ROOT=' + JSON.stringify(eccRoot) +
+    ' ECC_PLUGIN_ROOT=' + JSON.stringify(eccRoot) + ' ';
+  return prefix + command;
+}
+
+/**
+ * Convert the ECC hooks document into the DSH bridge format.
+ * Returns { config, report } where report lists skipped events/entries.
+ */
+function generateConfig(eccRoot, sourceDoc) {
+  const out = { hooks: {} };
+  const report = [];
+  for (const entry of Object.entries(sourceDoc.hooks || {})) {
+    const event = entry[0];
+    const groups = entry[1];
+    if (!SUPPORTED_EVENTS.has(event)) {
+      report.push('skip event ' + event + ' (not bridged by DSH)');
+      continue;
+    }
+    const outGroups = [];
+    for (const group of groups) {
+      const hooks = [];
+      for (const h of group.hooks || []) {
+        if (h.type !== 'command' || typeof h.command !== 'string') {
+          report.push('skip non-command hook on ' + event);
+          continue;
+        }
+        const mapped = { type: 'command', command: mapCommand(h.command, eccRoot) };
+        if (typeof h.timeout === 'number') mapped.timeout = h.timeout;
+        hooks.push(mapped);
+        report.push('ok ' + event);
+      }
+      if (hooks.length) {
+        outGroups.push({ matcher: mapMatcher(group.matcher), hooks: hooks });
+      }
+    }
+    if (outGroups.length) out.hooks[event] = outGroups;
+  }
+  return { config: out, report: report };
+}
+
+function main() {
+  const opts = parseArgs(process.argv);
+  const eccRoot = path.resolve(opts.eccRoot || path.join(__dirname, '..', '..'));
+  const sourcePath = path.join(eccRoot, 'hooks', 'hooks.json');
+  if (!fs.existsSync(sourcePath)) {
+    process.stderr.write('ECC hooks.json not found at ' + sourcePath + '\n');
+    process.exit(1);
+  }
+  let doc;
+  try {
+    doc = JSON.parse(fs.readFileSync(sourcePath, 'utf8'));
+  } catch (err) {
+    process.stderr.write('Failed to parse ' + sourcePath + ': ' + err.message + '\n');
+    process.exit(1);
+  }
+  const result = generateConfig(eccRoot, doc);
+  const outPath = opts.out || path.join(eccRoot, 'hooks', 'hooks.dsh.json');
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, JSON.stringify(result.config, null, 2) + '\n');
+  const okCount = result.report.filter(function (r) { return r.indexOf('ok ') === 0; }).length;
+  const notes = result.report.filter(function (r) { return r.indexOf('ok ') !== 0; });
+  process.stderr.write('wrote ' + outPath + '\n');
+  process.stderr.write('hook commands: ' + okCount + '\n');
+  if (notes.length) process.stderr.write(notes.join('; ') + '\n');
+}
+
+module.exports = { generateConfig, mapMatcher, mapCommand, SUPPORTED_EVENTS, TOOL_NAME_MAP };
+
+if (require.main === module) main();
diff --git a/skills/deepseek-harness-setup/SKILL.md b/skills/deepseek-harness-setup/SKILL.md
new file mode 100644
index 000000000..fd1b41d32
--- /dev/null
+++ b/skills/deepseek-harness-setup/SKILL.md
@@ -0,0 +1,79 @@
+---
+name: deepseek-harness-setup
+description: "Install and operate Everything Claude Code (ECC) on the DeepSeek Harness (DSH): native skill roots (~/.dsh/skills, .agents/skills), the @deepseek-ai/dsh-hooks-claude-code bridge for command hooks, bare-insert patch mounting, generator usage, event-support limits, and update workflow. Use when setting up ECC on DeepSeek Harness, wiring ECC hooks into a DSH profile, or debugging why ECC skills or hooks do not appear in a DSH session."
+metadata:
+  origin: community
+---
+
+# DeepSeek Harness Setup
+
+Run ECC on the DeepSeek Harness. Full guide: `docs/DEEPSEEK-HARNESS-GUIDE.md`.
+
+## When to Use
+
+- Installing ECC skills or hooks on a DeepSeek Harness install.
+- Deciding which ECC surfaces work on DSH and which do not.
+- Debugging a DSH session that does not show ECC skills or does not fire ECC hooks.
+
+## How It Works
+
+1. **Skills need no conversion.** DSH reads `SKILL.md` frontmatter
+   (name/description) from native skill roots. Link the ECC catalog once:
+
+   ```bash
+   ln -s /path/to/ECC/skills/<skill-name> ~/.dsh/skills/<skill-name>
+   ```
+
+   Root priority (project `.dsh` and `.agents` roots beat `~/.dsh`): skip
+   linking skills whose names already exist in a higher-priority root.
+
+2. **Hooks go through the first-party bridge.** Generate a DSH-format config
+   from the canonical ECC hooks file:
+
+   ```bash
+   node scripts/dsh/generate-hooks-config.js --ecc-root /path/to/ECC --out ~/.dsh/ecc/hooks-dsh.json
+   ```
+
+   The generator lower-cases tool-name matchers, prefixes
+   `CLAUDE_PLUGIN_ROOT`/`ECC_PLUGIN_ROOT` inline (the bridge does not export
+   the plugin root), preserves timeouts, and skips events DSH cannot bridge:
+   `PreCompact`, `PostToolUseFailure`, `SessionEnd`.
+
+3. **Mount with a bare insert** in `~/.dsh/profiles/<profile>/cordis.patch.yml`:
+
+   ```yaml
+   - insert:
+       - id: ecc-hooks-claude-code
+         name: "@deepseek-ai/dsh-hooks-claude-code"
+         config:
+           configPath: /absolute/path/to/hooks-dsh.json
+   ```
+
+   Loader rules that cost debugging time when learned the hard way:
+   a plain `- id:` top-level entry is silently dropped; `insert` under an
+   existing non-group id is rejected as "not a group"; first-party plugin
+   packages need no profile `package.json` entry.
+
+4. **Validate by composing, then verify live.**
+
+   ```bash
+   cd ~/.dsh && dsh --profile web --dump-config > /dev/null && echo OK
+   ```
+
+   A live GateGuard denial on the session's first edit/write/bash is the
+   visible signal the bridge is active.
+
+## Updating
+
+`git pull` reflects into linked skills immediately; regenerate the hooks
+config with the same generator command. If the ECC checkout moves, regenerate
+(the path is embedded in every hook command) and relink skills.
+
+## Limits
+
+| Surface | Status on DSH |
+|---------|---------------|
+| Skills | Full catalog works |
+| Hooks | 20 command hooks on 4 of 7 bridge events |
+| Slash commands | Not available (Claude Code mechanism); workflows covered by skills |
+| Agents | Not available as subagents; equivalent personas exist as skills |
diff --git a/tests/scripts/dsh-generate-hooks-config.test.js b/tests/scripts/dsh-generate-hooks-config.test.js
new file mode 100644
index 000000000..ebdd80253
--- /dev/null
+++ b/tests/scripts/dsh-generate-hooks-config.test.js
@@ -0,0 +1,104 @@
+/**
+ * Tests for scripts/dsh/generate-hooks-config.js
+ *
+ * Run with: node tests/scripts/dsh-generate-hooks-config.test.js
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const gen = require('../../scripts/dsh/generate-hooks-config');
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log('  \u2713 ' + name);
+    return true;
+  } catch (err) {
+    console.log('  \u2717 ' + name);
+    console.log('    Error: ' + err.message);
+    return false;
+  }
+}
+
+function runTests() {
+  let passed = 0;
+  let failed = 0;
+
+  if (test('mapMatcher maps Claude tool names to DSH lower-case names', () => {
+    assert.strictEqual(gen.mapMatcher('Bash'), 'bash');
+    assert.strictEqual(gen.mapMatcher('Edit|MultiEdit'), 'edit');
+    assert.strictEqual(gen.mapMatcher('Write|Edit|MultiEdit'), 'write|edit');
+  })) passed++; else failed++;
+
+  if (test('mapMatcher keeps regex passthrough tokens untouched', () => {
+    assert.strictEqual(gen.mapMatcher('.*'), '.*');
+    assert.strictEqual(gen.mapMatcher('^mcp__'), '^mcp__');
+    assert.strictEqual(gen.mapMatcher('.*|Task'), '.*|task');
+  })) passed++; else failed++;
+
+  if (test('mapCommand prefixes plugin-root env vars and keeps the resolver intact', () => {
+    const cmd = 'node -e "resolver" pretooluse:bash:check-console-log scripts/hooks/check-console-log.js standard';
+    const out = gen.mapCommand(cmd, '/ecc');
+    assert.strictEqual(out, 'CLAUDE_PLUGIN_ROOT="/ecc" ECC_PLUGIN_ROOT="/ecc" ' + cmd);
+  })) passed++; else failed++;
+
+  if (test('mapCommand passes through non-resolver commands with prefix only', () => {
+    const out = gen.mapCommand('echo hi', '/ecc');
+    assert.strictEqual(out, 'CLAUDE_PLUGIN_ROOT="/ecc" ECC_PLUGIN_ROOT="/ecc" echo hi');
+  })) passed++; else failed++;
+
+  if (test('generateConfig skips unsupported events and reports them', () => {
+    const doc = { hooks: {
+      PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'node -e "x" node scripts/hooks/a.js' }] }],
+      PreCompact: [{ matcher: '.*', hooks: [{ type: 'command', command: 'echo hi' }] }],
+      SessionEnd: [{ matcher: '.*', hooks: [{ type: 'command', command: 'echo hi' }] }],
+    } };
+    const { config, report } = gen.generateConfig('/ecc', doc);
+    assert.deepStrictEqual(Object.keys(config.hooks), ['PreToolUse']);
+    assert.ok(report.some(r => r.includes('PreCompact')));
+    assert.ok(report.some(r => r.includes('SessionEnd')));
+  })) passed++; else failed++;
+
+  if (test('generateConfig preserves timeout and maps matcher groups', () => {
+    const doc = { hooks: {
+      PostToolUse: [{ matcher: 'Edit|MultiEdit|Write', hooks: [
+        { type: 'command', command: 'node -e "x" node scripts/hooks/b.js', timeout: 30 },
+      ] }],
+    } };
+    const { config } = gen.generateConfig('/ecc', doc);
+    const g = config.hooks.PostToolUse[0];
+    assert.strictEqual(g.matcher, 'edit|write');
+    assert.strictEqual(g.hooks[0].timeout, 30);
+  })) passed++; else failed++;
+
+  if (test('generateConfig supports the bridge-only Subagent events', () => {
+    assert.ok(gen.SUPPORTED_EVENTS.has('SubagentStart'));
+    assert.ok(gen.SUPPORTED_EVENTS.has('SubagentStop'));
+  })) passed++; else failed++;
+
+  if (test('CLI end-to-end writes valid JSON to --out', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-dsh-'));
+    const outPath = path.join(tmp, 'hooks.dsh.json');
+    const repoRoot = path.resolve(__dirname, '..', '..');
+    const res = spawnSync('node', [
+      path.join(repoRoot, 'scripts', 'dsh', 'generate-hooks-config.js'),
+      '--ecc-root', repoRoot, '--out', outPath,
+    ], { encoding: 'utf8' });
+    assert.strictEqual(res.status, 0, 'CLI exit 0, stderr: ' + res.stderr);
+    const doc = JSON.parse(fs.readFileSync(outPath, 'utf8'));
+    assert.ok(doc.hooks.PreToolUse.length > 0, 'PreToolUse groups present');
+    assert.ok(Object.keys(doc.hooks).includes('SessionStart'));
+    assert.ok(!Object.keys(doc.hooks).includes('PreCompact'), 'unsupported event excluded');
+    fs.rmSync(tmp, { recursive: true, force: true });
+  })) passed++; else failed++;
+
+  console.log('');
+  console.log('Passed: ' + passed + ', Failed: ' + failed);
+  return failed === 0;
+}
+
+process.exit(runTests() ? 0 : 1);

From 3756908464be31a7901ba7703475237dd602d0b5 Mon Sep 17 00:00:00 2001
From: phungthien269 <phungthien269@users.noreply.github.com>
Date: Fri, 2 Oct 2026 00:26:01 +0700
Subject: [PATCH 2/3] feat: register DeepSeek Harness in the adapter compliance
 matrix

- Add deepseek-harness record (Adapter-backed) to ADAPTER_RECORDS with onramp, verification commands, risk notes, and source docs | - Regenerate the matrix block in docs/architecture/harness-adapter-compliance.md via the renderer | - Addresses the Harness-compatibility reference gap flagged by the ecc-tools Reference Set Readiness check on PR #3309
---
 .../harness-adapter-compliance.md             |  1 +
 scripts/lib/harness-adapter-compliance.js     | 39 +++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/docs/architecture/harness-adapter-compliance.md b/docs/architecture/harness-adapter-compliance.md
index 09061190d..b7f8c2b55 100644
--- a/docs/architecture/harness-adapter-compliance.md
+++ b/docs/architecture/harness-adapter-compliance.md
@@ -44,6 +44,7 @@ The matrix below is rendered from
 | Gemini | Instruction-backed | Gemini project-local instructions; shared skills; rules; compatibility docs | No full ECC hook parity; ecosystem ports must document drift from upstream ECC | `./install.sh --profile minimal --target gemini` | `node tests/lib/install-targets.test.js` | Treat Gemini ports as ecosystem adapters until validated end to end inside Gemini CLI. |
 | Zed | Adapter-backed | Zed project settings; flattened project rules; shared skills; commands; agents | Zed external agents and native Agent Panel permissions are not Claude hooks | `./install.sh --profile minimal --target zed` | `node tests/lib/install-targets.test.js`; `npm run harness:audit -- --format json` | Keep project settings conservative and do not copy BYOK/OpenRouter secrets into `.zed/`. |
 | dmux | Adapter-backed | session snapshots; tmux/worktree orchestration status; handoff exports | dmux is an orchestration runtime, not an install target for skills/rules | `node scripts/session-inspect.js --list-adapters`; dmux session target inspection | `node tests/lib/session-adapters.test.js` | Treat dmux events as session/runtime signals, not as a replacement for repo validation. |
+| DeepSeek Harness | Adapter-backed | canonical ECC skills (skills/) via native DSH skill roots; command hooks through the first-party @deepseek-ai/dsh-hooks-claude-code bridge (20 commands on 4 of 7 bridged events); hooks config generator (scripts/dsh/generate-hooks-config.js); profile patch mounting with compose-time validation | Claude slash commands and ECC subagent surfaces have no DSH equivalent; workflows are covered by skills; PreCompact, PostToolUseFailure, and SessionEnd hook events have no bridge counterpart; no dedicated installer target; setup is documented manual configuration | link the curated catalog: ln -s /path/to/ECC/skills/<skill> ~/.dsh/skills/<skill>; generate the hooks config: node scripts/dsh/generate-hooks-config.js --ecc-root /path/to/ECC --out ~/.dsh/ecc/hooks-dsh.json; mount a bare - insert: entry for @deepseek-ai/dsh-hooks-claude-code in ~/.dsh/profiles/<profile>/cordis.patch.yml | `node tests/scripts/dsh-generate-hooks-config.test.js`; `node scripts/ci/validate-skills.js`; `dsh --profile <profile> --dump-config` (compose-time validation) | Hook commands embed the ECC checkout path; regenerate the hooks config after moving the repo; Keep the tool-name matcher mapping (Bash to bash, Edit/MultiEdit to edit) in sync with DSH tool names; A plain top-level patch entry is silently dropped; additions require a bare insert entry |
 | Orca | Reference-only | worktree lifecycle; review state; notification; provider-identity design pressure | No ECC installer or direct adapter today | Use as a comparison target for worktree/session state requirements | `npm run observability:ready` | Do not import product-specific assumptions; convert lessons into ECC event fields. |
 | Superset | Reference-only | workspace presets; parallel-agent review loops; worktree isolation design pressure | No ECC installer or direct adapter today | Use as a comparison target for workspace preset taxonomy | `npm run observability:ready` | Keep ECC portable; do not require a desktop workspace to get basic value. |
 | Ghast | Reference-only | terminal-native pane grouping; cwd grouping; search; notifications | No ECC installer or direct adapter today | Use as a comparison target for terminal-first session grouping | `node scripts/session-inspect.js --list-adapters` | Preserve terminal ergonomics before adding visual UI assumptions. |
diff --git a/scripts/lib/harness-adapter-compliance.js b/scripts/lib/harness-adapter-compliance.js
index e1aafd752..1bf863a9b 100644
--- a/scripts/lib/harness-adapter-compliance.js
+++ b/scripts/lib/harness-adapter-compliance.js
@@ -254,6 +254,45 @@ const ADAPTER_RECORDS = Object.freeze([
       'tests/lib/session-adapters.test.js',
     ],
   },
+  {
+    id: 'deepseek-harness',
+    harness: 'DeepSeek Harness',
+    state: 'Adapter-backed',
+    supported_assets: [
+      'canonical ECC skills (skills/) via native DSH skill roots',
+      'command hooks through the first-party @deepseek-ai/dsh-hooks-claude-code bridge (20 commands on 4 of 7 bridged events)',
+      'hooks config generator (scripts/dsh/generate-hooks-config.js)',
+      'profile patch mounting with compose-time validation',
+    ],
+    unsupported_surfaces: [
+      'Claude slash commands and ECC subagent surfaces have no DSH equivalent; workflows are covered by skills',
+      'PreCompact, PostToolUseFailure, and SessionEnd hook events have no bridge counterpart',
+      'no dedicated installer target; setup is documented manual configuration',
+    ],
+    install_or_onramp: [
+      'link the curated catalog: ln -s /path/to/ECC/skills/<skill> ~/.dsh/skills/<skill>',
+      'generate the hooks config: node scripts/dsh/generate-hooks-config.js --ecc-root /path/to/ECC --out ~/.dsh/ecc/hooks-dsh.json',
+      'mount a bare - insert: entry for @deepseek-ai/dsh-hooks-claude-code in ~/.dsh/profiles/<profile>/cordis.patch.yml',
+    ],
+    verification_commands: [
+      '`node tests/scripts/dsh-generate-hooks-config.test.js`',
+      '`node scripts/ci/validate-skills.js`',
+      '`dsh --profile <profile> --dump-config` (compose-time validation)',
+    ],
+    risk_notes: [
+      'Hook commands embed the ECC checkout path; regenerate the hooks config after moving the repo',
+      'Keep the tool-name matcher mapping (Bash to bash, Edit/MultiEdit to edit) in sync with DSH tool names',
+      'A plain top-level patch entry is silently dropped; additions require a bare insert entry',
+    ],
+    last_verified_at: '2026-10-02',
+    owner: 'ECC maintainers',
+    source_docs: [
+      'docs/DEEPSEEK-HARNESS-GUIDE.md',
+      'skills/deepseek-harness-setup/SKILL.md',
+      'scripts/dsh/generate-hooks-config.js',
+      'tests/scripts/dsh-generate-hooks-config.test.js',
+    ],
+  },
   {
     id: 'orca',
     harness: 'Orca',

From 8fca8ef4aaf046e3d9de7329e69d0a1095ae49da Mon Sep 17 00:00:00 2001
From: phungthien269 <phungthien269@users.noreply.github.com>
Date: Fri, 2 Oct 2026 00:49:31 +0700
Subject: [PATCH 3/3] fix: address CodeRabbit and Greptile review findings

- Reject missing values for --ecc-root/--out with exit code 2 (CodeRabbit) | - Preserve regex matcher tokens with metacharacters or mcp__ prefixes from lower-casing (CodeRabbit) | - Shell-quote eccRoot in the env prefix to close CWE-78 command substitution (CodeRabbit, Greptile P1) | - Fix last_verified_at future date in the deepseek-harness record (CodeRabbit) | - Guide and skill: clarify skill-name placeholders and make the compose check verify the entry instead of echoing OK on exit status alone (Greptile P2 x2) | - Tests: 11 passing including new coverage for quoting, regex preservation, and flag validation
---
 docs/DEEPSEEK-HARNESS-GUIDE.md                | 15 +++++++++--
 scripts/dsh/generate-hooks-config.js          | 23 +++++++++++-----
 scripts/lib/harness-adapter-compliance.js     |  2 +-
 skills/deepseek-harness-setup/SKILL.md        | 12 ++++++---
 .../scripts/dsh-generate-hooks-config.test.js | 26 +++++++++++++++++--
 5 files changed, 64 insertions(+), 14 deletions(-)

diff --git a/docs/DEEPSEEK-HARNESS-GUIDE.md b/docs/DEEPSEEK-HARNESS-GUIDE.md
index 8d62c15fb..365287f16 100644
--- a/docs/DEEPSEEK-HARNESS-GUIDE.md
+++ b/docs/DEEPSEEK-HARNESS-GUIDE.md
@@ -35,6 +35,10 @@ To expose the full curated set in every project, link the catalog once:
 ln -s /path/to/ECC/skills/<skill-name> ~/.dsh/skills/<skill-name>
 ```
 
+Run this per skill with real names substituted for both placeholders (for
+example `ln -s ~/ECC/skills/tdd-workflow ~/.dsh/skills/tdd-workflow`); the
+angle brackets are placeholders, not shell syntax.
+
 DSH reads `SKILL.md` frontmatter (name/description), which matches the ECC skill
 format, so no conversion is needed. Name conflicts with pre-existing user skills
 are resolved by root priority; skip those skills when linking.
@@ -96,14 +100,21 @@ Configuration notes from practice:
 ### Verify
 
 ```bash
-# Compose check (no session boot)
-cd ~/.dsh && dsh --profile web --dump-config > /dev/null && echo OK
+# Compose check (no session boot). Keep stderr visible: silently dropped or
+# rejected patch entries are reported there while the exit status stays 0.
+cd ~/.dsh && dsh --profile web --dump-config > /tmp/dump.yml
+
+grep ecc-hooks /tmp/dump.yml
 
 # End-to-end: fire a SessionStart hook in a one-shot headless session
 # (uses a test config with a single marker-writing hook)
 dsh --profile headless --patch /tmp/ecc-patch-test.yml 'Reply with exactly: BOOT-OK'
 ```
 
+A successful compose does not prove the entry mounted: dropped entries and
+"is not a group" rejections only appear on stderr, never in the exit status.
+Confirm the entry id exists in the dump and that stderr was empty.
+
 In a live web session, the GateGuard fact-forcing hook denies the first
 edit/write/bash attempt until facts are presented — a visible signal that the
 bridge is active.
diff --git a/scripts/dsh/generate-hooks-config.js b/scripts/dsh/generate-hooks-config.js
index f66b82570..02e7abf93 100644
--- a/scripts/dsh/generate-hooks-config.js
+++ b/scripts/dsh/generate-hooks-config.js
@@ -45,8 +45,15 @@ function parseArgs(argv) {
   const opts = { eccRoot: null, out: null };
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
-    if (a === '--ecc-root') opts.eccRoot = argv[++i];
-    else if (a === '--out') opts.out = argv[++i];
+    if (a === '--ecc-root' || a === '--out') {
+      const value = argv[++i];
+      if (value === undefined || value.startsWith('--')) {
+        process.stderr.write('Missing value for ' + a + '\n');
+        process.exit(2);
+      }
+      if (a === '--ecc-root') opts.eccRoot = value;
+      else opts.out = value;
+    }
     else {
       process.stderr.write('Unknown argument: ' + a + '\n');
       process.exit(2);
@@ -64,7 +71,7 @@ function mapMatcher(matcher) {
   if (typeof matcher !== 'string' || matcher.length === 0) return matcher;
   const parts = matcher.split('|').map(function (t) {
     const v = t.trim();
-    if (v === '' || v === '.*' || v === '^mcp__') return v;
+    if (v === '' || /^\^?mcp__/.test(v) || /[\\^$.*+?()[\]{}]/.test(v)) return v;
     const mapped = TOOL_NAME_MAP[v];
     return mapped !== undefined ? mapped : v.toLowerCase();
   });
@@ -81,9 +88,13 @@ function mapMatcher(matcher) {
  * CLAUDE_PLUGIN_ROOT environment variable, so prefixing the variables
  * inline (env-prefix form) is the only required change.
  */
+function shellQuote(value) {
+  return "'" + String(value).replace(/'/g, "'\\''") + "'";
+}
+
 function mapCommand(command, eccRoot) {
-  const prefix = 'CLAUDE_PLUGIN_ROOT=' + JSON.stringify(eccRoot) +
-    ' ECC_PLUGIN_ROOT=' + JSON.stringify(eccRoot) + ' ';
+  const prefix = 'CLAUDE_PLUGIN_ROOT=' + shellQuote(eccRoot) +
+    ' ECC_PLUGIN_ROOT=' + shellQuote(eccRoot) + ' ';
   return prefix + command;
 }
 
@@ -149,6 +160,6 @@ function main() {
   if (notes.length) process.stderr.write(notes.join('; ') + '\n');
 }
 
-module.exports = { generateConfig, mapMatcher, mapCommand, SUPPORTED_EVENTS, TOOL_NAME_MAP };
+module.exports = { generateConfig, mapMatcher, mapCommand, shellQuote, SUPPORTED_EVENTS, TOOL_NAME_MAP };
 
 if (require.main === module) main();
diff --git a/scripts/lib/harness-adapter-compliance.js b/scripts/lib/harness-adapter-compliance.js
index 1bf863a9b..18fe3cc80 100644
--- a/scripts/lib/harness-adapter-compliance.js
+++ b/scripts/lib/harness-adapter-compliance.js
@@ -284,7 +284,7 @@ const ADAPTER_RECORDS = Object.freeze([
       'Keep the tool-name matcher mapping (Bash to bash, Edit/MultiEdit to edit) in sync with DSH tool names',
       'A plain top-level patch entry is silently dropped; additions require a bare insert entry',
     ],
-    last_verified_at: '2026-10-02',
+    last_verified_at: '2026-10-01',
     owner: 'ECC maintainers',
     source_docs: [
       'docs/DEEPSEEK-HARNESS-GUIDE.md',
diff --git a/skills/deepseek-harness-setup/SKILL.md b/skills/deepseek-harness-setup/SKILL.md
index fd1b41d32..265ee829c 100644
--- a/skills/deepseek-harness-setup/SKILL.md
+++ b/skills/deepseek-harness-setup/SKILL.md
@@ -26,6 +26,8 @@ Run ECC on the DeepSeek Harness. Full guide: `docs/DEEPSEEK-HARNESS-GUIDE.md`.
 
    Root priority (project `.dsh` and `.agents` roots beat `~/.dsh`): skip
    linking skills whose names already exist in a higher-priority root.
+   Substitute real skill names for the placeholders; the angle brackets are
+   not shell syntax.
 
 2. **Hooks go through the first-party bridge.** Generate a DSH-format config
    from the canonical ECC hooks file:
@@ -57,11 +59,15 @@ Run ECC on the DeepSeek Harness. Full guide: `docs/DEEPSEEK-HARNESS-GUIDE.md`.
 4. **Validate by composing, then verify live.**
 
    ```bash
-   cd ~/.dsh && dsh --profile web --dump-config > /dev/null && echo OK
+   cd ~/.dsh && dsh --profile web --dump-config > /tmp/dump.yml
+   grep ecc-hooks /tmp/dump.yml
    ```
 
-   A live GateGuard denial on the session's first edit/write/bash is the
-   visible signal the bridge is active.
+   Compose exit status stays 0 even when the loader drops or rejects an
+   entry — those problems are only reported on stderr. Confirm the entry id
+   appears in the dump and stderr is empty. A live GateGuard denial on the
+   session's first edit/write/bash is the visible signal the bridge is
+   active.
 
 ## Updating
 
diff --git a/tests/scripts/dsh-generate-hooks-config.test.js b/tests/scripts/dsh-generate-hooks-config.test.js
index ebdd80253..468016efe 100644
--- a/tests/scripts/dsh-generate-hooks-config.test.js
+++ b/tests/scripts/dsh-generate-hooks-config.test.js
@@ -43,12 +43,12 @@ function runTests() {
   if (test('mapCommand prefixes plugin-root env vars and keeps the resolver intact', () => {
     const cmd = 'node -e "resolver" pretooluse:bash:check-console-log scripts/hooks/check-console-log.js standard';
     const out = gen.mapCommand(cmd, '/ecc');
-    assert.strictEqual(out, 'CLAUDE_PLUGIN_ROOT="/ecc" ECC_PLUGIN_ROOT="/ecc" ' + cmd);
+    assert.strictEqual(out, 'CLAUDE_PLUGIN_ROOT=\'/ecc\' ECC_PLUGIN_ROOT=\'/ecc\' ' + cmd);
   })) passed++; else failed++;
 
   if (test('mapCommand passes through non-resolver commands with prefix only', () => {
     const out = gen.mapCommand('echo hi', '/ecc');
-    assert.strictEqual(out, 'CLAUDE_PLUGIN_ROOT="/ecc" ECC_PLUGIN_ROOT="/ecc" echo hi');
+    assert.strictEqual(out, 'CLAUDE_PLUGIN_ROOT=\'/ecc\' ECC_PLUGIN_ROOT=\'/ecc\' echo hi');
   })) passed++; else failed++;
 
   if (test('generateConfig skips unsupported events and reports them', () => {
@@ -80,6 +80,28 @@ function runTests() {
     assert.ok(gen.SUPPORTED_EVENTS.has('SubagentStop'));
   })) passed++; else failed++;
 
+  if (test('mapMatcher preserves case-sensitive regex tokens with metacharacters', () => {
+    assert.strictEqual(gen.mapMatcher('^mcp__GitHub__.*'), '^mcp__GitHub__.*');
+    assert.strictEqual(gen.mapMatcher('\\S'), '\\S');
+  })) passed++; else failed++;
+
+  if (test('mapCommand shell-quotes dangerous path characters', () => {
+    const dollar = gen.mapCommand('echo hi', '/home/u/$proj');
+    assert.ok(dollar.startsWith("CLAUDE_PLUGIN_ROOT='/home/u/$proj' "), 'literal inside single quotes: ' + dollar);
+    const quoted = gen.mapCommand('echo hi', "/home/u'z");
+    assert.ok(quoted.startsWith("CLAUDE_PLUGIN_ROOT='/home/u'\\''z' "), 'embedded quote escaped: ' + quoted);
+  })) passed++; else failed++;
+
+  if (test('CLI rejects missing flag values with exit code 2', () => {
+    const repoRoot = path.resolve(__dirname, '..', '..');
+    const res = spawnSync('node', [
+      path.join(repoRoot, 'scripts', 'dsh', 'generate-hooks-config.js'),
+      '--ecc-root',
+    ], { encoding: 'utf8' });
+    assert.strictEqual(res.status, 2, 'exit 2 on missing value, stderr: ' + res.stderr);
+    assert.ok(res.stderr.includes('Missing value for --ecc-root'));
+  })) passed++; else failed++;
+
   if (test('CLI end-to-end writes valid JSON to --out', () => {
     const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'ecc-dsh-'));
     const outPath = path.join(tmp, 'hooks.dsh.json');