@maci0/dsh-feynman 0.0.0-stage → 0.21.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcel W. Wysocki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,7 @@
+DSH Feynman: provenance notice
+
+Workflow behavior adapted from Feynman (https://www.feynman.is/docs).
+© Companion, Inc. The prompts in this repository are original briefs written
+from the documented behavior, not copied text.
+
+This project is distributed under the MIT License; see LICENSE.

package/README.md

@@ -1,3 +1,126 @@
-# Temporary Holding Version
+# dsh-feynman
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A question lands mid-session: *what are the current approaches to mechanistic interpretability?* You type `/feynman deepresearch "mechanistic interpretability"`, the brief becomes the agent's next turn, and a cited research document lands in `outputs/`. That is the whole trick: 27 subcommands that queue a workflow as the next turn instead of making you describe the workflow in prose. Adapted from [Feynman](https://www.feynman.is/docs/reference/slash-commands) (see [licence](#licence)); the prompts are original briefs written from the documented behaviour, not copied text.
+
+## What you get
+
+- **14 research workflows** behind one `/feynman` dispatcher: deep research, literature review, severity-graded critique, a bounded review loop, paper-vs-code audit, replication plans, ML recipes, source comparison, drafting, autonomy loops, topic watching, PaperRank, full-text access, pandoc preview.
+- **13 session commands** for the housekeeping around that work: logs, jobs, artifact listing, key status, session search, doctor.
+- **A real review loop.** `/feynman review-loop` keeps iterating review → fix → re-review on its own: when a round's turn completes, the next round is queued, until rounds run out. `/feynman review-loop stop` ends it early.
+- **A subcommand picker.** Bare `/feynman` opens a popup listing every subcommand with its arguments; picking a row submits `/feynman <sub>`.
+- **A Research Keys card** on the **Plugins** page: open the `dsh-feynman` bundle, then the `feynman` row's **Configure** control. Hugging Face and AlphaXiv keys are stored through the credentials domain, never in settings.
+- **Key-aware briefs.** Every workflow brief names the live credential refs and treats an unset one as blocked instead of guessing.
+
+## Install
+
+> **Install it as a bundle.** `dsh plugin add …` mounts the row from the
+> package's own patch layer, which is what the settings editor can write to. A
+> row added with `--patch` is an overlay: it disappears at the next start, and
+> the Plugins card cannot save into it (the editor refuses a write an overlay
+> would win).
+
+```sh
+dsh plugin --profile web add github:maci0/dsh-feynman#v0.21.3
+```
+
+Pin a release tag: a bare `github:` spec floats on `main`. To upgrade, run the
+same command with the newer tag, then restart `dsh web` (bundle layers compose
+at boot).
+
+## Commands
+
+Quick check after the restart: `/feynman doctor` reports key state, mounted seams, pandoc, and the config card.
+
+Every workflow subcommand queues its brief as the agent's next turn; the queued turn *is* the work.
+
+| Command | What it produces |
+|---|---|
+| `/feynman deepresearch <topic>` | Research brief: Summary, Background, Key Findings, Open Questions, References, plus a provenance sidecar. Plan is confirmed before execution. |
+| `/feynman lit <topic-or-lab>` | Literature review: consensus, disagreements, open questions, timeline. Lab/PI corpus mode keeps a reachable-publication log. |
+| `/feynman review <arXiv-ID \| URL \| file>` | Severity-graded critique (critical/major/minor/nit) with confidence scores. Draft evidence under `outputs/.drafts/`. |
+| `/feynman review-loop <artifact> [rounds]` | Bounded review → fix → re-review loop. Default 3 rounds; a count outside 1 to 10 is clamped to that range. `stop` ends it early. DSH-native, no upstream equivalent. |
+| `/feynman audit <repo> [--paper <id>]` | Paper-vs-code mismatch report with file paths and line numbers. Repo found via paper links, Papers With Code, GitHub search. |
+| `/feynman replicate <paper-or-claim>` | Replication plan. Executes only after you pick an environment; a result is `replicated` only when the planned checks pass. |
+| `/feynman recipe <task>` | Ranked implementable ML training recipes with dataset, method, and hyperparameter links. |
+| `/feynman compare <topic-or-sources>` | Agreement/disagreement matrix across sources. |
+| `/feynman draft <topic \| --from-session>` | Academic draft with inline citations. Unsupported claims become TODOs, never invented. |
+| `/feynman autoresearch <idea>` | Bounded hypothesis → experiment → analysis → decision loop against a benchmark (log, JSONL, CHANGELOG milestones). |
+| `/feynman watch <topic>` | Baseline survey plus a refresh plan. Each check compares against the baseline. |
+| `/feynman rank <topic> [flags]` | PaperRank: run manifest, ranked brief, paper/score JSONL, score audit, citation graph + HTML explorer, field map, sensitivity data, provenance. |
+| `/feynman paper <id> [--fetch-full-text] [--json]` | Legal full-text access candidates, no paywall bypasses. Writes `<slug>-paper-access.md` and `.json`. |
+| `/feynman preview [artifact]` | Pandoc render of an artifact (HTML/PDF). |
+
+Session subcommands: `log`, `jobs`, `help`, `feynman-model`, `init`, `outputs`, `btw`, `thinking`, `search`, `web-results`, `keys`, `doctor`, `status`.
+
+`/feynman search <query>` runs a real full-text search over prior sessions and prints matching session ids with excerpts. The other seam-backed commands (`jobs`, `web-results`) degrade to an error or one line of guidance when their seam is not mounted, never to a success message claiming work happened.
+
+Rank example:
+
+```
+/feynman rank "scaling laws" --limit 20 --json
+/feynman rank "scaling laws" --expand-citations 2 --full-text-top 3 --critique-top 5
+/feynman rank "scaling laws" --preference-file preferences.json --reproduction-notes notes.json --synthesize --synthesis-model provider/model
+```
+
+Unknown `--flags` are rejected, never absorbed into the topic.
+
+## Configure
+
+Row config in the Loader entry:
+
+| Field | Default | Meaning |
+|---|---|---|
+| `hfTokenEnv` | `HF_TOKEN` | Env-var name holding the Hugging Face key. |
+| `alphaxivTokenEnv` | `ALPHAXIV_API_KEY` | Env-var name holding the AlphaXiv key. |
+
+A value that is not an env-var name (letters, digits, underscore) fails the row at load. Loop and rank cadences are fixed in code: `/feynman review-loop` runs 3 rounds by default with a cap of 10, and `/feynman rank` lists 20 papers by default with a cap of 100.
+
+Keys, in precedence order (environment shadows the store):
+
+1. **Config card**: password field per key, set/unset badge (unknown, with the reason as a tooltip, when the lookup fails), Save, Clear.
+2. **Shell**: `export HF_TOKEN=hf_… ALPHAXIV_API_KEY=…` before launch.
+3. **Command**: `/feynman keys` shows status without echoing values; `/feynman keys set <hf|alphaxiv> <value>` stores into `$DSH_HOME/.credentials.yaml`.
+
+`HUGGINGFACE_HUB_TOKEN` works too: point `hfTokenEnv` at it. The AlphaXiv key is spent through `web_fetch` against the AlphaXiv API; without it, briefs fall back to arXiv and OpenAlex and mark citation-metadata and discussion checks blocked.
+
+## How it works
+
+Each subcommand queues a frozen user message as the agent's next turn. The message is built with `createUserMessage` and branded with a plugin source, so the harness does not mistake it for human typing. The queued turn is the work.
+
+A review-loop round is the turn that carries the loop's own queued message (the harness records it as that turn's `user/message`). Only that turn's completion queues the next round, so a turn already running when the loop starts, or a turn you send in between, does not count. A round turn that ends any other way (error, abort, blocked, token limit) ends the loop; start it again to continue.
+
+Retrieval maps to `web_search` / `web_fetch` plus the workspace tools (`read`, `grep`, `glob`, `bash`); there are no separate paper or dataset tools. Broad work fans out through the `subagent` tool, narrow explainers stay lead-owned.
+
+Artifacts land under `outputs/`: `*-brief.md`, `*-lit-review.md`, `*-review.md`, `*-audit.md`, and so on. `/feynman outputs` lists them; `/feynman log` writes the session log. Rank writes the full PaperRank set (`*-research-run.json`, `*-papers.jsonl`, `*-scores.jsonl`, `*-score-audit.md`, `*-citation-graph.json`, `*-graph-explorer.html`, `*-field-map.json`, `*-rank-sensitivity.json`, `*-rank.provenance.md`) plus critique, calibration, reproduction, and synthesis outputs when the matching flags are passed.
+
+The package declares `dsh.bundle`, so `dsh plugin add` appends it to `dsh.profile.bundles` and the shipped `cordis.patch.yml` applies as a layer. Do not also paste that row into the profile's own `cordis.patch.yml`: `insert` does not dedupe ids, so the plugin would mount twice.
+
+## Limits
+
+- **The picker submits the bare subcommand.** A subcommand that needs an argument answers with its usage line; type the argument after it.
+- **Attachments ride only on subcommands that queue a model message**: the workflows, `log`, `init`, `outputs`, and `btw`. Any other subcommand refuses an invocation that carries attachments, so the composer keeps them.
+- **Review-loop state is instance-local.** Loops live in the `apply` closure, keyed by session id, and a disposed session drops its loop. A profile restart forgets them.
+- **A browser-half edit needs a page refresh.** The client module system serves `exports["./client"]` from the package; the host half can stay up.
+- **Host source edits remount only with `id: hmr` enabled** and this checkout in `config.root`. Without it, a live patch reload re-runs `apply` from the module already in memory.
+- **Ranking is a live heuristic.** Scores are computed transparently in-session and the output says so. They are not a fitted model and not a deterministic scorer.
+- **One locale.** The card ships English copy; other active locales fall back to it. The browser bundle exports only `apply` and `inject`, and registers one locale dictionary.
+- **No paywall bypasses, ever.** Unreachable sources are marked blocked, never inferred.
+
+## Development
+
+Plain JavaScript, no build step. `index.js` is the host half, `prompts.js` is the pure workflow catalog (no harness imports), `lib/client.js` is the browser half.
+
+```sh
+bun install --frozen-lockfile
+bun test
+```
+
+dsh loads plugins on Node `^22.19.0 || >=24.0.0`; development and tests run on bun.
+
+Coverage: prompt construction, dispatcher registration for every subcommand, attachment refusal, review-loop rounds through the agents registry, per-instance loop state, credential-ref validation failures, jobs and session search against fake seams, the card's registration, hook order, ready-gating, and non-leaking of key literals, and a real Cordis composition.
+
+For local development, `dsh plugin --profile <name> add <path-to-checkout>`.
+
+## Licence
+
+MIT. Workflow behaviour adapted from [Feynman](https://www.feynman.is/docs) © Companion, Inc.; the prompts are original briefs. DSH port: see `LICENSE`.

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# Bundle layer: applied when a profile lists this bundle in dsh.profile.bundles
+# (dsh plugin add does that from dsh.bundle). That list is frozen at boot.
+# Do not also paste this row into the profile's cordis.patch.yml: insert does
+# not dedupe ids, two rows would register the plugin twice.
+- insert:
+    - id: feynman
+      name: '@maci0/dsh-feynman'

package/icon.svg

@@ -0,0 +1,6 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg">
+  <rect x="6" y="7" width="24" height="17" rx="2" fill="#16324F"/>
+  <path d="M10 14.5h7M10 18.5h5" stroke="#E8F1FF" stroke-width="1.6" stroke-linecap="round"/>
+  <circle cx="23.5" cy="16" r="3.1" stroke="#7CB7FF" stroke-width="1.6"/>
+  <path d="M14 26.5h8" stroke="#8AA0B8" stroke-width="2.2" stroke-linecap="round"/>
+</svg>