dsh-research

dsh-research (alpha.4)

Research as a folder the agent fills and the right bar shows — and that you keep, open in any session, and edit yourself.

A run is RUN.json plus a passport.json that records your instructions and every answer in your own words. Nine rs_* tools work over an append-only claim and source ledger; a human answers the frame gates in the Research tab rather than the model; every claim in the prose is a span the ledger tracks, so a citation that does not exist cannot be built into a document without being reported by name — and a claim that rests on a number carries that number as data, so the build prints every statistic the document claims instead of leaving it buried in a sentence.

Most "write me a paper" surfaces produce text that lives in the chat and dies there, and the one quiet catastrophe of research tooling is a citation — or a claim — that nothing can check. This package starts from the other end: it builds the record first.

What it adds

• Nine tools, named by intent. rs_open (where runs live, what is in each, where this one stands — and action=handoff, which reprints the ledger so a model's summary is never mistaken for what you said), rs_new (start a run; opens the frame gates), rs_plan (the question, the outline, the method), rs_read (the one reader: view, gates, passport, files, claims, sources, outline, build, or one text file), rs_write (write prose AND declare the claims it makes, together), rs_cite (ingest a source: hash the bytes, store the record and the text), rs_verify (run the two rungs a file can run, record the two that need a reader), rs_review (the panel, the author's answers, the re-review, and the devil's advocate), rs_build (a watermarked draft, or a gated clean document).
• A structured method record, and the counts that cannot be true. rs_plan part=method method={…} writes plan/method.json: databases, accessed, search, include, exclude and screening (identified, screened, included), plus optional registration, platforms and notes. It is validated on the way in — a date that does not exist, a field this package does not read, and a required field left out are each refused — and again by r0 on the way out, because a record a person edited by hand never passed the first check. The one arithmetic a review can lie to itself with is checked rather than trusted: records are removed at each step, never added, so identified >= screened >= included. A record that breaks it is refused (METHOD_COUNTS); an incomplete one is an r0 warning, method-incomplete. plan/method.md is generated from the record, and the build prints the whole thing into the document as a search-and-screening flow — the same numbers, from the same bytes, in every artifact. A run with no record is not a failure: a theoretical paper has no search, and the build reports the absence as a note.
• A statistic is data, not prose. A claim that rests on a number takes statistic: { test, statistic, df, p, effect, ci, n }, validated like everything else in the dialect. Two of its rules are reporting standards rather than taste: p = .000 is refused (no test produces a probability of exactly zero — it is what a program prints after rounding — and the refusal names p .md and reviews/traceability.md on disk, which is what a response-to-reviewers letter is written from.
• The devil's advocate's protocol is enforced, not requested. action=attack raises one, action=concede records a concession — and it needs the rebuttal's score (1–5, how directly and how evidential the reply was). Below 4 the concession is refused (CONCESSION_BELOW_THRESHOLD): the advocate holds position and restates the attack. Two concessions in a row are refused outright (CONSECUTIVE_CONCESSION) — the sycophancy pattern the protocol exists to slow, where every individual concession looks reasonable and the sequence is agreement with extra steps. The report also prints the concession rate and says the pattern out loud when it crosses half.
• A ladder, and every rung names what it reached.
  • r0-structure — the document and its ledgers agree (span-unrecorded, claim-orphan, broken-marker, broken-citation, unknown-source). Runs in doc.js, on every entry the panel saves.
  • r1-record — the stored bytes still hash to the names they are filed under (bytes-tampered), the record has the fields a reference needs, every field names its origin, and the title it claims actually appears in the text that was ingested (title-mismatch). This is PROVENANCE, not existence: it never says a DOI is real.
  • r2-locate — every claim's quoted passage really is in its source's stored text. A miss and an inconclusive are different answers: a quote that is not found is locate-miss only when the extraction reports complete coverage, and locate-inconclusive otherwise — because telling an author their quote is not in the paper when the extractor was partial is the worst answer this plugin could give.
  • r3-support / r4-audit — a reader's judgement, recorded by the agent with rs_verify action=support / audit, with the judge named and the passage quoted. A claim with no locator cannot be judged (STATUS_REQUIRES_EVIDENCE): there is no passage that was read. An audit before an r3 verdict is refused (RUNG_ORDER). A verdict with no reason is refused — a score with no evidence is the one thing this ledger must not hold.
  • A rung that could not run says so. A source with no stored text is uncheckable, listed by name, never a pass — the quiet failure being a run that looks fully checked because every check that could not run was skipped.
• A run is a real folder you keep. ~/Desktop/vncode-research// by default, with plan/, doc/, ledger/, sources/, figures/, reviews/, build/. DSH_RESEARCH_ROOT overrides it; a machine with no Desktop falls back to /research.
• A library pointer, so every session agrees. $DSH_HOME/dsh-research/library.json names the folder your runs live in, and the first session that resolves a root writes it. Open a paper tomorrow, from another conversation, with a different working directory: it is the same folder. Delete the file to let the next session choose again. rs_open action=roots prints it.
• A passport, not a preference file. The initial instruction verbatim, every gate question with its answer and timestamp, every override's reason, and a receipt per tool call. A second answer to the same gate is refused: a ledger that can be edited in place is not a ledger.
• Two frame gates, and one that a clean build opens.
  • g1-rq — is this the research question you actually want answered, and is it yours? rs_write refuses until this is answered: writing the document before the question is confirmed is the failure this plugin exists to prevent.
  • g2-intake — does this document report experiments that you ran? Fail-closed: it wants your words even when the answer is a plain "no", and it does not block a write, because it is about what the document reports rather than whether it may be written.
  • g3-integrity — opened by rs_build draft=clean, the mode whose output looks finished. A clean build also refuses while the document and its ledger disagree, or while a claim a check found unsupported is still in the text.
• A document dialect with exactly one addition to Pandoc Markdown. [the sentence, as written]{#c0142} is a claim; [@key], [@key, p. 7] and [-@key] are citations. rs_write refuses a span with no ledger row, a row with no span, a citation whose key no source defines (offering the nearest keys), and a citation-shaped bracket that does not parse — because each of those is a claim or a citation with nothing behind it.
• The ledger is append-only, one row per revision. Changing a claim's wording clears its verification, and the answer says so: a verdict belongs to a sentence, not to an id. A row that would change nothing is not appended, so a ledger's length means "how many times something actually changed".
• Six citation styles, as data. APA 7, Chicago notes, Chicago author-date, MLA 9, IEEE, Vancouver — one module each behind a registry, with the reference list computed from the ledger rather than typed by the model. Every one of them prints the source's address, because a citation a reader cannot follow is a citation that does not work.
• It builds the document, and the DOCX is written rather than wrapped. rs_build format=md writes the reader-ready Markdown — citations resolved by the style, the reference list computed from the ledger, claim endnotes in a draft. format=docx writes a real Office document from the same Markdown, through seven modules of hand-written OOXML (lib/docx/: a ZIP writer with fixed timestamps, the part model, styles, numbering, footnotes, tables, images) — which is the only way to keep the promise that this plugin spawns no process, since calling pandoc would be one. Two builds of one run are byte-identical: the writer never reads the clock, and a check holds it to that. format=html writes one self-contained page — no stylesheet URL, no font, no script, no remote image — and only the URL schemes a document may legitimately cite survive into it (javascript: is dropped rather than emitted). format=tex writes a .tex that needs no bibliography engine, because the citations are already resolved and the reference list already computed; it prints the pdflatex command rather than running it, which is what a package that spawns no process can honestly do. ris / bib / enw export the run's whole library for Zotero, EndNote or pandoc. The DOCX was verified by an independent tag-balance check, a CRC read of its own ZIP central directory, and pandoc reading the file back — including the metadata, the aligned table, the nested list and both footnotes.
• Submission packaging, which is a folder and not a file. format=package assembles what a journal actually asks for: manuscript.docx built with no title block, so it carries nothing identifying; title-page.md (uploaded separately, with the placeholders a person fills in); cover-letter.md computed from the ledger rather than written from memory — the claim counts, the verification state and the experiment-intake answer come from the run, so a letter cannot describe a paper that does not exist; CHECKLIST.md, which says what the run says about its own evidence and what no builder can check for you ("read it once with fresh eyes: the builder removed the title block, and it cannot know what your prose reveals"); and the run's figures/ copied beside them. It is gated like a clean build whatever draft says, because a submission is the artifact that must not carry a claim nothing has checked.
• The Research tab, and it is editable. The run list with a "waiting" badge; the pending gates as a form (question, options, a box for your words, a reason box for an override, Submit); answered gates as a timeline; the passport's provenance quoted untruncated; the files. **A .md file under doc/ or plan/ opens in an e