dsh-backstory

dsh-backstory

English · 中文

Ask any line of code its backstory — what it does, and why it's here.

A DeepSeek Harness (dsh) plugin.
git blame tells you who wrote a line and when. dsh-backstory adds the part
that actually matters when you're staring at unfamiliar code: what it does and
why it exists — grounded in the commit that last touched it and in the agent's
own history: which turn wrote each line, and the prompt that triggered it.

backstory  src/blame.ts:27
──────────────────────────────────────────────────────────────
L27 · a5d49e9  2026-08-20 — "feat: dsh-backstory v0.1 …"
    const header = /^([0-9a-f]{40}) \d+ (\d+)(?: \d+)?$/.exec(raw)

→ WHAT: matches a `git blame --line-porcelain` header line (sha + line numbers)
→ WHY : commit "dsh-backstory v0.1" — starts a new blame record for each line

Why it's different

• git blame → who / when / which commit.

• dsh-backstory → what the line does + why it's here, in one place.

• Not a generic "explain this code" (any LLM does that). The why comes from
  real repository history, so the answer is grounded, not guessed.

• When the agent itself wrote a line, it adds a dsh-native origin that
  git blame can never give you — which turn wrote it, and your prompt —
  per line (🧬t14) and for the file:

  L1 · a5d49e9 … 🧬t14
      export const greeting_de = "Willkommen"
  🧬 origin · turn 14 — you asked: "支持德语双语" [ledger-hash]
  

Provenance: three layers

Each queried line is attributed by whichever source is most precise, in order:

1. Ledger content-hash ([ledger-hash]) — every write/edit is recorded to a
   repo-committed .dsh/backstory.jsonl with the touched lines' content hashes.
   A line is matched by its text, so it survives moving up/down the file
   (line-number drift). This persists across sessions, machines, and people.
2. Commit trailer ([commit]) — once work is committed with DSH-Turn /
   DSH-Prompt trailers, git blame → sha → trailer recovers the provenance and
   git's own line tracking handles drift for free.
3. Live session log ([session]) — for the current session before anything
   is written to the ledger, reconstructed from exec.agent.session.events.

All three degrade gracefully: no ledger, no trailers, no git — you still get the
source lines back.

Install

dsh plugin add dsh-backstory      # once published to npm

When installed, the dsh host applies the bundle patch declared in
package.json (dsh.bundle.patch → cordis.patch.yml),
which inserts the plugin into the running composition. No extra wiring needed.

Or run from source for local development:

git clone https://github.com/MeghanBao/dsh-backstory.git
cd dsh-backstory
npm run typecheck   # tsc --noEmit
npm test            # blame parser, provenance engine, git-blame e2e

The standalone cordis.yml loads just this plugin for local
iteration.

Usage

Type the /backstory command, optionally with a file and line range:

/backstory src/auth.ts:40-60
/backstory utils/date.ts

Or just ask the agent in natural language (it uses the same backstory tool):

• "what's the backstory of src/auth.ts line 88?"
• "explain utils/date.ts lines 10–40 and why each part is there"

The tool returns each line with the commit that last touched it (author, date,
message) and — when known — the agent turn/prompt that wrote it (🧬t<turn>).
The agent narrates what the code does and uses the commit message + origin for
why. Outside a git repo it degrades gracefully to source-only.

Tool: backstory

Param	Type	Notes
path	string (required)	absolute or workspace-relative
line	number	first line (1-based); omit for the whole file
endLine	number	last line; defaults to line

Whole-file reads are bounded to 400 lines.

The ledger & commit trailers

The plugin records every write/edit to .dsh/backstory.jsonl automatically
(via a tools/post-execute observer) — commit that file to make provenance
travel with the repo.

To also anchor provenance in git history (drift handled by git), install the
prepare-commit-msg hook once per clone:

npm run install-hook

From then on every commit gets the newest ledger record for its staged files
folded into trailers automatically:

DSH-Turn: 14
DSH-Prompt: 支持德语双语
DSH-Session: 0f3a…

The hook is best-effort (never blocks a commit), idempotent (safe on --amend),
and self-disabling if removed. It backs up any existing hook to *.backup.

Incremental explanations

Explaining a line costs a model call, so explanations are cached. After the agent
explains the unexplained lines from a backstory result, it calls
backstory_remember to store them — keyed by each line's content hash, in
.dsh/backstory-notes.jsonl. Next time, unchanged lines come back with their
explanation already attached (↳), and only lines whose text changed need
re-explaining. Cheap, and never stale.

Privacy: redaction & opt-out

Prompts are stored in the ledger (and, via the hook, in commit trailers), so
common secrets are scrubbed automatically before they are written — OpenAI /
GitHub / AWS / Slack / Google keys, JWTs, Bearer tokens, and key=value pairs
for password / token / secret / api_key become [REDACTED].

Turn recording off, or add your own patterns, via .dsh/backstory.config.json:

{ "record": true, "redactPatterns": ["ACME-\\d+"] }

Or disable it everywhere with an env var: DSH_BACKSTORY_DISABLE=1.

⚠️ Redaction is best-effort pattern matching, not a guarantee — review commits
before pushing, and opt out for anything sensitive.

Roadmap

• v0.1 — git-history backstory: line → commit → what/why. ✅
• v0.2 — dsh-native half: reconstruct which agent turn wrote a file and the
  prompt that triggered it, from the live session log (file-level). ✅
• v0.3a — persistent line-level ledger: record every write/edit to
  .dsh/backstory.jsonl (turn, prompt, touched lines, content hashes); survives
  across sessions/machines/people. ✅
• v0.3b — drift-proof attribution: match a line by its content hash, so
  provenance survives the line moving in the file. ✅
• v0.4 — git-native provenance: DSH-* commit trailers, recovered via
  git blame → sha → trailer, with drift handled by git itself; plus a
  prepare-commit-msg hook installer (npm run install-hook) that folds ledger
  records into trailers automatically. ✅
• v0.5 — privacy: automatic secret redaction in stored prompts + a
  .dsh/backstory.config.json / DSH_BACKSTORY_DISABLE opt-out. ✅
• v0.6 — a /backstory user command (registered as a dsh skill) that
  drives the tool with a file:line argument. ✅
• v0.7 — incremental explanations: cache per-line explanations by content
  hash (backstory_remember → .dsh/backstory-notes.jsonl); only re-explain
  lines that changed. ✅

Status

Built against the dsh developer preview — APIs may shift. The blame parser,
provenance engine, ledger, hash attribution, git-blame and commit-trailer paths
are covered by 43 tests (pure logic + e2e against real temp repos). Every
runtime touchpoint (exec.agent.session.events, the tools/post-execute
recorder) is defensive and degrades gracefully, so the tool never breaks.

License

MIT © Meghan Bao