dsh-researcher

English | 简体中文

Stop AI coding agents from forgetting project reality—or declaring DONE without evidence

dsh-researcher is an experimental governance layer for DeepSeek Harness. It separates two jobs that ordinary Plan mode tends to mix:

• Project Research reconstructs purpose, architecture, constraints, risks, and unknowns inside a guarded read-only session.
• Goal Governor freezes the target, boundaries, budget, human gates, and definition of done; the host then derives the terminal state from trusted events instead of assistant prose.

They are independent. You can trial Project Research without adopting Goal Contracts.

Honest maturity: the mechanisms, installer lifecycle, adversarial replay, and offline E1 infrastructure are tested. Live E1, net productivity gain, long-term Project Cognition value, and adapters beyond DSH are not proven.

The problem

AI coding becomes unreliable across sessions, not only within one prompt:

1. A new session re-guesses why the repository exists.
2. Locally plausible changes slowly cross architecture or migration boundaries.
3. An agent says “done” without sufficient outcome evidence—or keeps polishing after the task is already satisfied.
4. The person never froze a stopping condition, so neither side knows when to stop.

A Plan says what steps may be attempted. This project records what is believed true, what must be achieved, who may prove it, and when work must stop.

See the mechanism in 60 seconds

The public demo is offline and starts real verifier child processes. It uses a synthetic DSH-shaped event envelope, so it proves reducer behavior—not Live DSH or model productivity.

git clone https://github.com/TLNing260310/dsh-researcher.git
cd dsh-researcher
npm run demo

The three decisions are reproducible:

assistant says DONE, no trusted evidence  → CONTINUE
matching verifier exits 1                → CONTINUE
matching verifier exits 0 after repair   → DONE

The final assistant message is never evidence. A MUST criterion is satisfied only by a host event bound to an approved verifier's tool name, complete arguments, argument hash, and result policy.

Choose only the layer you need

Safe trial on DeepSeek Harness

Requirements:

• DeepSeek Harness: exactly verified against 0.1.0-rc.7.
• Node.js: >=22.12.0.
• Use an isolated DSH_HOME and a non-critical repository copy first.

This repository is GitHub-distributed only. The unscoped npm name dsh-researcher belongs to a different maintainer and repository. Do not use npm install dsh-researcher; use the pinned GitHub source or signed release assets below. main now uses the private scoped identity @tlning260310/dsh-researcher to prevent accidental publication under the wrong identity. The existing v0.8.0-alpha.8 tag predates that metadata change, but its github: source remains unambiguous and never resolves the npm registry package.

Preview every installer-owned change first:

npx -y github:TLNing260310/dsh-researcher#v0.8.0-alpha.8 --dry-run

Install only after reviewing the preview:

npx -y github:TLNing260310/dsh-researcher#v0.8.0-alpha.8

The installer refuses unknown DSH versions and existing presets by default. Backup, force-upgrade, uninstall, rollback, and SHA-256-bound release installation are documented in Safe installation and recovery.

Path A: read-only Project Research

1. Start a new DSH Web session and select Read Only.
2. Select 项目研究 Project Research. The preset tightens approval to never.
3. Ask a bounded, evidence-oriented question:

Run research_doctor first. Review this repository without writing files.
Use path:line evidence to explain its purpose, immutable constraints,
documentation/implementation conflicts, and the next hypothesis worth testing.
Mark anything unverified as UNKNOWN.

research_doctor must be the first tool call. Research remains locked unless the Runtime Certificate is SAFE; later permission drift revokes the certificate before another model response.

Two entry points exist:

The real smoke proves the runtime boundary, not report quality. Two local 14B probes failed to produce a publishable report; that negative evidence remains public in Project Research local-output smoke.

Path B: a review-first Goal Contract

The Quickstart generates external Cognition, Verifier Registry, Goal Contract, and REVIEW.md drafts. It does not approve a goal or promote project facts for you.

npx -y --package=github:TLNing260310/dsh-researcher#v0.8.0-alpha.8 project-cognition init .
npx -y --package=github:TLNing260310/dsh-researcher#v0.8.0-alpha.8 project-cognition quickstart --root . --out ../my-goal-review --goal-id fix-login-timeout

Review purpose, boundaries, MUST criteria, budget, and verifier definitions in the generated REVIEW.md, then follow its explicit approval commands. See the five-minute Quickstart.

What “done” means here

• Every MUST criterion needs a frozen verifier or direct human gate.
• The final attempt re-proves every MUST; it cannot inherit an old attempt's success.
• An already-passing baseline returns ALREADY_SATISFIED without a performative code change.
• Attempt, time, token, or no-progress budgets end in STOPPED.
• Contract, cognition, permission, or verifier drift ends in NEEDS_HUMAN.
• A model cannot write or replace its own terminal decision; the host recomputes it from the trusted event prefix.

Authority flow

read-only research
  → Research Session Ledger (non-authoritative)
  → draft revision
  → owner review
  → seal
  → .project-cognition/state.json (canonical truth)
  → deterministic PROJECT_COGNITION.md projection

Goal Contract + frozen verifier registry
  → host-observed calls, results, gates, usage, and repository revision
  → replay / reducer
  → CONTINUE | NEEDS_HUMAN | DONE | STOPPED

The CLI actor label is not human authentication. Repository governance must keep approval authority outside the model workflow.

Evidence ledger

Run the public offline checks without a model or network call:

npm run check
npm run demo
npm run eval:e1:preflight

The proof order is frozen as Gate 0 → E1 → non-inferential pilot → E2 → second-adapter conformance → E3. See Validation Status and the protocol-owned Goal Governor evaluation definition.

How this differs from familiar tools

Spec Kit, OpenSpec, Kiro, Serena, Beads, and client-native Plan/Memory may be better choices for many users. The candidate differentiation here is the combination of staleable project reality and host-owned terminal adjudication, not any individual feature. See the competitive and integration landscape.

Repository map

• Mature project introduction
• Safe installation and recovery
• Five-minute Quickstart
• Validation Status
• Architecture
• Goal Governor guide
• Project Cognition governance
• Case library and admission standard
• E1 harness

Feedback

You do not need a polished report. The most useful signals are whether the demo ran, where installation stopped, whether the workflow prevented a wrong completion, and whether it added only overhead.

• Submit a 10-minute trial report
• Share a full real-world run
• Open a reproducible bug
• Report security issues privately under SECURITY.md.

Current release: v0.8.0-alpha.8. The alpha line is intentionally frozen until a meaningful evidence or onboarding milestone; documentation changes on main are not a new product claim.