@ericrisco/rsc 3.0.6 → 3.0.8

package/README.md

@@ -31,6 +31,27 @@ npx @ericrisco/rsc@latest onboard
 
 </div>
 
+## 🐋 New: DeepSeek Harness
+
+[DeepSeek Harness](https://www.npmjs.com/package/@deepseek-ai/dsh) (`dsh`) is now a supported
+assistant, the 18th. Pick it in the wizard or pass `--target deepseek`:
+
+```bash
+npx @ericrisco/rsc@latest onboard --target deepseek
+```
+
+- **Skills** go to `.dsh/skills/`, where dsh finds them on its own.
+- **Instructions** go in the rsc block of `AGENTS.md`, which dsh already reads.
+- **Session memory, knowledge sync and the update notice** run from dsh's own hooks. dsh has no
+  hooks per project, so rsc adds one marked block to `~/.dsh/cordis.patch.yml` once per machine. That
+  block runs the hooks of whichever project the session is in. It works in `dsh web` with several
+  projects open, and in a project without rsc it does nothing. Restart dsh once after the first
+  install. To turn it off, delete the block.
+
+Details: [targets table](#multi-target).
+
+---
+
 ## Your agent needs a harness. It should not improvise one.
 
 A model is only the brain. Real work also needs project memory, tools, domain knowledge, rules and
@@ -73,7 +94,7 @@ rsc 3.0 fixes all four, by default, with no new commands to learn:
 | **You choose how the project works** | The install asks once: straight on `main`, or branches and pull requests? Branches are recommended only for long-lived, complex code. With `main` the agent works on it and never asks about branches. With branches a commit on `main` is refused, and before each code change the agent asks: this branch, a new one, or unlock `main`? It never opens a branch on its own. | Say **«unlock main»** / **«lock main»**, or `rsc main unlock` / `lock` |
 | **One workspace per agent** | If another assistant session is working in the same folder, new work goes to a worktree under `.worktrees/<branch>/`. It stays inside the project, is never committed, and is removed once that branch is merged. | `rsc isolation off` |
 | **The agent picks the method** | A simple change takes Fast-Track (one document, proof for every task). Something big or complex takes the spec-driven chain. The agent decides and says why. You still approve *what* gets built: the spec and the clarifications, then step by step or autopilot. | Ask for the other lane |
-| **Knowledge reaches everyone** | `01-TOOLS/` and `02-DOCS/` travel through one exchange branch, `rsc/knowledge`. They go up when your turn ends and come down into whatever branch each person is on. They reach `main` inside your normal pull requests. | `rsc knowledge-sync off` |
+| **Knowledge reaches everyone** | `01-TOOLS/`, `02-DOCS/wiki/` and `02-DOCS/attachments/` travel through one exchange branch, `rsc/knowledge`. They go up when your turn ends and come down into whatever branch each person is on. They reach `main` inside your normal pull requests. | `rsc knowledge-sync off` |
 
 **Commit, push and pull request without a prompt each time.** A harness installed from scratch lets
 the agent run `git commit`, `git push` and `gh pr create` without asking, because those are the steps
@@ -89,6 +110,7 @@ someone runs `rsc git-permissions on`.
 | Gemini | `.gemini/settings.json` → `tools.allowed` |
 | OpenCode | `opencode.json` → `permission.bash` (force-push → `ask`) |
 | Cursor | Not covered: its CLI matches only the first word, so allowing a push would allow every git command. |
+| DeepSeek Harness | Not covered: dsh has no per-command allow list. Its own Permissions selector (`/permission`) sets approval for every command at once. |
 
 ```bash
 rsc git-permissions status   # decided or not, and wired per assistant
@@ -241,8 +263,8 @@ no method deciding whether each piece belongs. rsc-harness keeps that constructi
 - **Specialists follow the stack.** The four base agents stay small; installing a
   supported stack adds only its reviewer and build resolver. `rsc add go`, for
   example, adds the Go pair without pulling reviewers for every other language.
-- **A new local session continues the old one.** Claude Code, Codex, Gemini CLI
-  and OpenCode load a bounded checkpoint for the current branch and worktree at
+- **A new local session continues the old one.** Claude Code, Codex, Gemini CLI,
+  OpenCode and DeepSeek Harness load a bounded checkpoint for the current branch and worktree at
   session start. Cursor desktop uses an assisted read-before-action fallback.
 - **Honestly good.** Every skill was built by a research → spec → implement →
   *adversarial review* pipeline and had to clear an objective rubric
@@ -262,7 +284,8 @@ When a new session opens in the same checkout, that state is injected before the
 first agent action. A completed edit is preserved even if the previous client
 closed before its normal session-end event.
 
-- **Full:** Claude Code, Codex, Gemini CLI and OpenCode. Codex asks you to inspect
+- **Full:** Claude Code, Codex, Gemini CLI, OpenCode and DeepSeek Harness (through rsc's machine
+  bridge, see [targets](#multi-target)). Codex asks you to inspect
   and trust the project hook once with `/hooks`; until then `doctor` reports that
   trust is still required.
 - **Assisted:** Cursor desktop. Its start hook is fire-and-forget, so rsc also
@@ -448,8 +471,10 @@ list somebody has to remember to update is a list that goes quietly stale. Decla
 
 ### Your wiki and tools stay in sync — on by default
 
-`01-TOOLS/` and `02-DOCS/` are the team's knowledge, so rsc keeps them the same on every machine
-without anybody thinking about git, **and without ever pushing to `main`**. Your `main` is
+`01-TOOLS/`, `02-DOCS/wiki/` and `02-DOCS/attachments/` are the team's knowledge, so rsc keeps them
+the same on every machine without anybody thinking about git, **and without ever pushing to `main`**.
+Exactly those three folders, minus rsc's own `01-TOOLS/_TEMPLATE/` and your personal
+`02-DOCS/wiki/harness/user-profile.md`. Your `main` is
 protected, or should be; rsc assumes it is.
 
 The knowledge travels through one exchange branch, `rsc/knowledge`, that nobody works on by hand:
@@ -461,13 +486,22 @@ main   · protected      untouched — gets it inside the next merged pull reque
 new    · clones main    has it all after the first message
 ```
 
-- **When a turn ends**, your changes in those folders are committed as `📝 docs(auto): … [skip ci]`
-  and sent to `rsc/knowledge` on `origin`, from whatever branch you are on. If you are on a closed
-  `main`, nothing is committed locally: the snapshot is built aside and only goes to `rsc/knowledge`.
-  Knowledge that you or the agent already **committed** on the branch during the turn goes up too —
-  only its `01-TOOLS/` and `02-DOCS/` part, under a `docs(auto) … [skip ci]` message.
-- **Before each message**, what teammates sent is brought into **the branch you are on**, and you are
-  told in one line. Only the knowledge folders are touched.
+- **When a turn ends**, your changes in those folders are committed on your branch as
+  `📝 docs(auto): …` and sent to `rsc/knowledge` on `origin`, from whatever branch you are on. Only
+  the copy on `rsc/knowledge` carries `[skip ci]`; the commit on your branch does not, so your next
+  ordinary push still runs CI. Two cases commit nothing on your branch: a closed `main`, and code of
+  yours still uncommitted (a docs commit would land ahead of the code it describes). Then the snapshot
+  is built aside, only goes to `rsc/knowledge`, and the files stay modified for you to commit with
+  your work. Knowledge that you or the agent already **committed** on the branch goes up too — only
+  its knowledge part, under a `docs(auto) … [skip ci]` message. Commits that came in by merging
+  `main` are your teammates', not yours, and are not sent again.
+- **Before each message**, what teammates sent is brought into **the branch you are on** as a
+  `📥 docs(auto): sync` commit, and you are told in one line. Only the knowledge folders are touched.
+  A doc that `main` on `origin` already has, identical, is left for your ordinary merge of `main`. On
+  a closed `main` nothing is written at all — an uncommitted file there would make your next
+  `git pull` refuse to run — you are told what is waiting, and it arrives with that pull or in the
+  next branch you open. When the last fetch is more than ten minutes old, the message fetches first
+  (three seconds at most), so even a one-message session sees fresh docs.
   A branch you open later catches up on its first message: everything on `rsc/knowledge` since it
   left `main` comes down, including what you wrote yourself on another branch.
 - **It reaches `main` the normal way.** Your feature branch now carries the team's knowledge, so it
@@ -482,14 +516,14 @@ What it will not do, by design:
 | --- | --- |
 | Push to `main` | Never. Only `rsc/knowledge` receives anything. |
 | Push your code or your unpushed commits | Only the knowledge folders go up, even from a commit that also has code. Your code waits for you. |
-| Trigger CI or a deploy | Every automatic commit says `[skip ci]`. |
+| Trigger CI or a deploy | Every commit on `rsc/knowledge` says `[skip ci]`; the one on your branch does not, so it never skips the CI of your own push. |
 | Bring in anybody else's code | Only knowledge paths come down. Code, config and `.claude/` are never pulled. |
 | Sync `02-DOCS/wiki/harness/user-profile.md` | Those are one person's dials. |
 | Overwrite a file you are editing | It tells you, and your version stays. |
 | Run where it has no business | No `origin`, no knowledge folders, a rebase in progress, a cloud agent: it stays quiet. |
 
 It is wired into the assistant's own turn hooks (end of turn, new message) in Claude Code, Codex,
-Gemini, Cursor and OpenCode (tested end to end in Claude Code, Codex and OpenCode). The network part runs in the background, so a turn never waits for
+Gemini, Cursor, OpenCode and DeepSeek Harness (tested end to end in Claude Code, Codex and OpenCode). The network part runs in the background, so a turn never waits for
 it. It is kept apart from the [local session memory](#new-sessions-pick-up-the-latest-local-work),
 which promises never to touch the network. The first turn says it is on. To turn it off for the
 project:
@@ -550,7 +584,7 @@ A new install asks whether you want this (yes by default). To turn it off later,
 `.rsc.json` like the other switches. The update can leave harness files changed in git; rsc never
 commits them for you.
 
-Where it runs on its own: **Claude Code, Codex, Gemini CLI, Cursor and OpenCode**, from a
+Where it runs on its own: **Claude Code, Codex, Gemini CLI, Cursor, OpenCode and DeepSeek Harness**, from a
 session-start hook. Every other assistant has no such hook, so the always-on instructions ask the
 agent to run `node .rsc/auto-update.mjs` on its first turn — same rules, but it depends on the agent
 doing it (and some assistants ask your permission before running a command). Codex asks you to
@@ -772,14 +806,23 @@ duplicated. The wizard asks which ones; `--target a,b` does it non-interactively
 | `roo` | `.roo/rsc/<id>/` → symlink | rule in `.roo/rules/rsc-suggest.md` |
 | `amp` | `.amp/rsc/<id>/` → symlink | block in `AGENTS.md` |
 | `opencode` | `.opencode/rsc/<id>/` → symlink | block in `AGENTS.md` |
+| `deepseek` | `.dsh/skills/<id>/` → symlink (DeepSeek Harness discovers it natively) | block in `AGENTS.md` |
 | `jules` | `.jules/rsc/<id>/` → symlink | block in `AGENTS.md` |
 | `junie` | `.junie/rsc/<id>/` → symlink | block in `.junie/guidelines.md` |
 | `kiro` | `.kiro/rsc/<id>/` → symlink | doc in `.kiro/steering/rsc-suggest.md` |
 | `aider` | `.aider/rsc/<id>/` → symlink | block in `CONVENTIONS.md` |
 
-> `codex`, `zed`, `amp`, `opencode` and `jules` all share the one root
+> `codex`, `zed`, `amp`, `opencode`, `deepseek` and `jules` all share the one root
 > `AGENTS.md`; the block is idempotent, so picking several writes it once.
 
+> **DeepSeek Harness** (`dsh`) has no project-level hook config: its plugins are per machine. So
+> the `deepseek` target writes the project hooks to `.dsh/hooks.json` (Codex format, untracked) and,
+> once per machine, adds one marked block to `~/.dsh/cordis.patch.yml` (or `$DSH_HOME`) that mounts
+> dsh's Codex-hooks bridge on rsc's dispatcher in `~/.dsh/rsc/`. The dispatcher runs the hooks of
+> whichever project the session is in, so `dsh web` serving several workspaces works too, and a
+> project without rsc runs nothing. Restart dsh once after the first install. Delete the block to
+> turn it off.
+
 The richer surfaces are intentionally narrower than skill support:
 
 | Targets | Stack agents | Native commands | Local session continuation |
@@ -788,6 +831,7 @@ The richer surfaces are intentionally narrower than skill support:
 | Codex | yes | no separate project-command surface | full after `/hooks` trust |
 | Cursor desktop | yes | yes | assisted |
 | Gemini CLI, OpenCode | yes | yes | full |
+| DeepSeek Harness | unsupported | unsupported | full (through the machine bridge) |
 | GitHub Copilot | yes | yes | unsupported |
 | Junie, Kiro | yes | unsupported | unsupported |
 | Windsurf, Cline, Roo | unsupported | yes | unsupported |

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.0.6",
+  "version": "3.0.8",
   "counts": {
     "skills": 270,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "3.0.6",
+  "version": "3.0.8",
   "description": "A guided harness builder that turns your goal into a minimal, verified AI-agent setup using strict best practices.",
   "type": "module",
   "bin": {
@@ -46,6 +46,8 @@
     "claude-code",
     "cursor",
     "codex",
+    "deepseek",
+    "deepseek-harness",
     "gemini",
     "antigravity",
     "cli",

package/scripts/audit.js

@@ -207,6 +207,17 @@ export function stampAudit(cwd, date = new Date().toISOString()) {
   writeFileSync(join(dir, 'audit.json'), JSON.stringify({ lastRun: date }, null, 2) + '\n');
 }
 
+// The start of the cadence for a harness that has never been audited: written by onboarding so the
+// first audit falls due STALE_DAYS after install, not in the first session. `baseline` and not
+// `lastRun`, because no audit ran — the SessionStart hook reads either. Leaves an existing file alone.
+export function recordAuditBaseline(cwd, date = new Date().toISOString()) {
+  const file = join(cwd, '.rsc', 'audit.json');
+  if (existsSync(file)) return false;
+  mkdirSync(join(cwd, '.rsc'), { recursive: true });
+  writeFileSync(file, JSON.stringify({ baseline: date }, null, 2) + '\n');
+  return true;
+}
+
 // Write the report into the harness wiki when one exists; always stamp .rsc/audit.json.
 export function writeAuditReport(report, cwd = process.cwd()) {
   const written = [];

package/scripts/doctor.js

@@ -1,6 +1,7 @@
-import { hooksDir, hooksDirIsOurs } from '../targets/worktree-reaper.mjs';
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import { hooksDir, hooksDirIsOurs, classifyWorktrees } from '../targets/worktree-reaper.mjs';
+import { existsSync, readFileSync, readdirSync, statSync, realpathSync } from 'node:fs';
+import { join, dirname, relative, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { homedir } from 'node:os';
 import { targetPaths, TARGET_IDS } from '../targets/index.js';
 import { readState } from './lib/state.js';
@@ -101,7 +102,18 @@ export function missingHookScripts({ target, home = homedir(), cwd = process.cwd
 // Is the post-merge trigger actually armed in this clone? Three states, because they need three
 // different answers: armed, absent (repair it), or someone else's (leave it — chaining is our job
 // at install time, and overwriting a husky hook to fix a convenience would be indefensible).
-function worktreeCleanupStatus(root) {
+// The skills that read or write a design identity (02-DOCS/wiki/brand/) or a starting point. The
+// state is always reported; the FIX — "run design-loop, then design-dna" — is advice, and advice needs
+// evidence. A todo web app with none of these installed was told to run two skills it does not have
+// and never asked for (E2E 2026-10-07).
+const DESIGN_SKILLS = new Set(['design', 'design-loop', 'design-dna', 'brand-voice', 'content-engine', 'marketing', 'presentations', 'make']);
+function withoutUnfoundedFix(summary, inPlay) {
+  if (inPlay || !summary || !summary.fix) return summary;
+  const { fix, ...rest } = summary;
+  return { ...rest, note: 'no design skill is installed here, so nothing is recommended' };
+}
+
+function worktreeCleanupStatus(root, policy) {
   if (!existsSync(join(root, '.git'))) return { state: 'not-a-repo' };
   if (existsSync(join(root, '.rsc', '.no-worktree-cleanup'))) return { state: 'off-by-choice' };
   // Ask git where hooks live instead of assuming `.git/hooks`. Until 2.0.1 this read the assumed
@@ -118,6 +130,13 @@ function worktreeCleanupStatus(root) {
   }
   const hook = join(dir, 'post-merge');
   if (!existsSync(hook)) {
+    // The merge hook is one of the code hooks, and the accepted plan can defer those. Recommending
+    // `repair` then is a loop with no exit — repair re-runs the same install, which honours the same
+    // plan and skips the hook again — and it contradicted `healthy: true` on every fresh small
+    // software install (E2E 2026-10-07). Said as what it is, with nothing to do.
+    if (policy?.codeHooks === false) {
+      return { state: 'not-in-plan', reason: 'the accepted plan defers code hooks, and the post-merge cleanup is one of them; `rsc reassess` revisits that.' };
+    }
     return { state: 'absent', action: 'Run `npx @ericrisco/rsc repair` to arm the post-merge cleanup in this clone.' };
   }
   try {
@@ -128,6 +147,27 @@ function worktreeCleanupStatus(root) {
   } catch { return { state: 'unreadable' }; }
 }
 
+// The two things a team trips over with worktrees (team simulation D9): a `.worktrees/` git does not
+// ignore — one `git add -A` away from committing a whole checkout — and landed worktrees still on
+// disk, which look exactly like live ones. Reported with the way out, never blocking `healthy`: both
+// cost tidiness, not work.
+const realOf = (p) => { try { return realpathSync.native(p); } catch { return p; } };
+function worktreeHygiene(root) {
+  if (!existsSync(join(root, '.git'))) return { state: 'not-a-repo' };
+  const probe = spawnSync('git', ['-C', root, 'check-ignore', '-q', '--no-index', '.worktrees/rsc-probe/file'], { encoding: 'utf8' });
+  const ignored = probe.status === 0;
+  let leftovers = [];
+  try {
+    leftovers = classifyWorktrees(root)
+      .filter((c) => c.verdict === 'safe' || c.verdict === 'ask')
+      .map((c) => ({ path: relative(realOf(root), c.path).split(sep).join('/') || c.path, branch: c.branch, verdict: c.verdict }));
+  } catch { /* unanswerable is not a finding */ }
+  const actions = [];
+  if (!ignored) actions.push('`.worktrees/` is not ignored by git here: run `npx @ericrisco/rsc sync` (it adds it to the rsc block of .gitignore) and commit .gitignore so every clone gets it.');
+  if (leftovers.length) actions.push(`${leftovers.length} landed worktree(s) are still on disk: \`npx @ericrisco/rsc worktrees\` lists them, \`npx @ericrisco/rsc worktrees reap\` removes the safe ones.`);
+  return { ignored, leftovers, ...(actions.length ? { action: actions.join(' ') } : {}) };
+}
+
 // Every skill this catalog ships declares `origin: risco` in its own frontmatter — all 272 of them,
 // uniformly. So "is this ours?" is answerable from the file itself, and does not need the list in
 // `.rsc.json` that nobody ever filled: that list is parallel accounting (P3), it has been empty in
@@ -184,8 +224,8 @@ export function doctor({ target, home, cwd }) {
     try {
       memory.metrics = hasStore
         ? metricsSummary({ cwd: root })
-        : { sessions: [], total: { cost: null, toolCalls: null }, knownTotal: { cost: 0, toolCalls: 0 }, unknown: { cost: 0, toolCalls: 0 } };
-    } catch { memory.metrics = { sessions: [], total: { cost: null, toolCalls: null }, knownTotal: { cost: 0, toolCalls: 0 }, unknown: { cost: 0, toolCalls: 0 } }; }
+        : { sessions: [], total: { cost: null, toolCalls: null }, knownTotal: { cost: null, toolCalls: null }, unknown: { cost: 0, toolCalls: 0 } };
+    } catch { memory.metrics = { sessions: [], total: { cost: null, toolCalls: null }, knownTotal: { cost: null, toolCalls: null }, unknown: { cost: 0, toolCalls: 0 } }; }
   }
   const actualSkills = listSkills({ target, home, cwd: root }).map((entry) => entry.id);
   const actualAgents = listAgents({ target, home, cwd: root }).agents.map((entry) => entry.id);
@@ -208,6 +248,9 @@ export function doctor({ target, home, cwd }) {
     const path = agentPath(target, root, id);
     return path && !existsSync(path);
   }).map((id) => ({ id, path: agentPath(target, root, id), action: 'Run `npx @ericrisco/rsc sync` to restore this managed agent.' }));
+  // What THIS harness installed, not every skill visible from here: a design skill in the user's
+  // global scope is how a todo app's doctor came to recommend design-dna (E2E 2026-10-07).
+  const designInPlay = Object.keys(state.skills || {}).some((id) => DESIGN_SKILLS.has(id));
   const report = {
     target,
     installed: Object.keys(state.skills),
@@ -224,17 +267,18 @@ export function doctor({ target, home, cwd }) {
     // The worktree cleanup's trigger is a git hook, and `.git/hooks/` is not cloned. So a repo can
     // carry a perfectly healthy harness and still never clean up, on every machine but the one that
     // ran the installer. Reported, never nagged about: `repair` is what puts it back (P6).
-    worktreeCleanup: worktreeCleanupStatus(root),
+    worktreeCleanup: worktreeCleanupStatus(root, state.policy),
+    worktreeHygiene: worktreeHygiene(root),
     ownSkills: ownSkillsIn(paths, readProjectManifest(root)?.ownSkills || []),
     sello: selloStatus(root),
     // Whether this harness has a design identity at all. `design` has always DECLARED that it
     // stops without one; until lib/design-identity.js nothing checked it (P2). Reported here,
     // never nagged about and never blocking: a missing identity is low risk (P7).
-    designIdentity: designIdentity(root),
+    designIdentity: withoutUnfoundedFix(designIdentity(root), designInPlay),
     // The other half of the same question: an identity is what this project settled on, a starting
     // point is what it has to settle FROM. Three skills promise to propose one and none could look;
     // this is the look. One field, not a section — a report grows for every user who runs it (P5).
-    designStartingPoint: startingPointSummary(root),
+    designStartingPoint: withoutUnfoundedFix(startingPointSummary(root), designInPlay),
     // An inert gate must never read as an armed one (the same rule the sello follows):
     // the gitmoji guard has a per-project kill switch, so say which state it is in.
     gitmojiGuard: state.policy?.gitmojiGuard === false
@@ -306,9 +350,17 @@ const bytesOf = (p) => { try { return statSync(p).size; } catch { return 0; } };
 
 // The always-on body a wired scope injects: the hook command embeds the exact SKILL.md path,
 // so read it from there rather than guessing the layout.
+// The body the SessionStart hook prints is the `.md` file its command names — today the short
+// `.rsc/suggest-always-on.md`, not the whole `suggest` SKILL.md. Reading only `…SKILL.md` out of the
+// command meant the current wiring never matched and the fallback counted the full skill: doctor said
+// 7.1 KB for a hook that injects 0.3 KB of body (E2E 2026-10-07). The command names the project
+// through ${CLAUDE_PROJECT_DIR}, so that is resolved against the scope before measuring.
 function alwaysOnBytesFor(scopeRoot, settingsRaw) {
-  const fromCommand = /"([^"]*suggest[^"]*SKILL\.md)"/.exec(settingsRaw || '');
-  if (fromCommand && bytesOf(fromCommand[1])) return bytesOf(fromCommand[1]);
+  const raw = (settingsRaw || '').replace(/\\\\/g, '/');
+  const candidates = [...raw.matchAll(/\\?"([^"\\]*suggest[^"\\]*\.md)\\?"/g)].map((m) => m[1]
+    .replace(/\$\{CLAUDE_PROJECT_DIR\}|\$CLAUDE_PROJECT_DIR/g, scopeRoot)
+    .replace(/^~(?=\/)/, homedir()));
+  for (const file of candidates) if (bytesOf(file)) return bytesOf(file);
   return bytesOf(join(scopeRoot, '.rsc', 'skills', 'suggest', 'SKILL.md'));
 }