falsify-dsh

Readme

# falsify-dsh

English | [中文](README.zh.md)

DeepSeek writes. Falsify asks: where is the evidence?

After install, tell the agent “falsify this file” or “gate this PR.”
You get a receipt: `PASS` / `PASS_WITH_DEBT` / `BLOCK`.
Agent “looks fine” is not a receipt. Green lint is not a ship.

Official site: [https://falsify.site/](https://falsify.site/)

## 30-second install

### 1. Public Falsify CLI

Python 3.12+:

```sh
pip install "falsify @ git+https://github.com/shi275773124/Falsify.git"
python -m falsify --help
```

### 2. This bundle

```sh
dsh plugin --profile web add "github:shi275773124/falsify-dsh#v0.1.0"
```

### 3. Restart the profile

```sh
dsh --profile web
```

Only packages that declare `dsh.bundle.patch` become active profile layers. This package does.

Optional: set `FALSIFY_PYTHON` if `python` is not the interpreter that has Falsify installed.

## Say this

After the plugin is enabled, tell the agent:

- `falsify this file`
- `gate this PR`
- `static check this file`

Or call the tools directly: `falsify_lint`, `falsify_review`, `falsify_gate`.

The CLI is the adjudicator. The plugin only supplies paths, runs `python -m falsify`, and returns a receipt. Agents do not choose the verdict.

## Developer preview

DeepSeek Harness is currently in _developer preview_ and is iterating rapidly. **THERE WILL BE COMPATIBILITY-BREAKING CHANGES.**

This adapter follows that preview. A green lint, demo, or selftest is **not** claim-bearing authority. `dsh-inspect` hunts problems and repairs them. `falsify-dsh` only wraps the public MIT Falsify CLI.

## Tools

| Tool | Public CLI | What it is allowed to mean |
|---|---|---|
| `falsify_lint` | `python -m falsify lint` | `L2_CLEAN` / `L2_DIRTY`. Static tags + blocker markers. Ceiling = `NONE`. |
| `falsify_review` | `python -m falsify review --json` | `PASS` / `PASS_WITH_DEBT` / `BLOCK`. Epistemic document review. Not live. |
| `falsify_gate` | `python -m falsify gate --json` | Public gate receipt. `production` / `quant` fail closed without a Pro adapter. |

The adapter never invents a `PASS`. If the CLI is missing, the verdict is `CLI_ERROR`, not a silent green.

## Compatibility

| Piece | Pin |
|---|---|
| DSH | developer preview, last checked against `deepseek-ai/deepseek-harness` on 2026-08-13. `@deepseek-ai/dsh-tools` is supplied by the profile, not npm. |
| Node | `^22.19.0 \|\| >=24.0.0` |
| Public Falsify CLI | [shi275773124/Falsify](https://github.com/shi275773124/Falsify) `>=0.6.0` |
| Verified DSH commit | not yet runtime-tested against a frozen DSH SHA — see Known limitations |

Old receipts stay receipts. They are not upgraded into later authority.

## Uninstall

```sh
dsh plugin --profile web remove falsify-dsh
```

Or delete the dependency from the profile `package.json` and run `dsh plugin --profile web update`. Restart the profile afterwards. The adapter does not write durable state of its own.

### Run the adapter tests from source

```sh
git clone https://github.com/shi275773124/falsify-dsh.git
cd falsify-dsh
npm install
npm test
```

## Configuration

| Key / env | Default | Meaning |
|---|---|---|
| `python` / `FALSIFY_PYTHON` | `python` | Interpreter that can run `python -m falsify` |
| `timeoutMs` / `FALSIFY_DSH_TIMEOUT_MS` | `180000` | Hard timeout; abort is `CLI_ERROR`, not PASS |
| `DEEPSEEK_API_KEY` / `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` | unset | Passed through to the public CLI for `falsify_review` |
| `FALSIFY_PROVIDER` / `FALSIFY_MODEL` / `FALSIFY_BASE` | unset | Optional CLI defaults |

There is no Falsify cloud key. Review is BYOK.

## Permissions and data

The adapter:

- spawns a local Python process (`python -m falsify …`)
- reads the subject file or a temp copy of inline text
- writes a temp JSON file for `falsify_gate --json`
- forwards provider API keys already present in the environment
- does **not** upload receipts, open network sockets of its own, or claim production authority

The child CLI may call a model provider if you configured one. That is the public Falsify CLI's job, not this adapter's.

## Troubleshooting

| Symptom | What it actually means |
|---|---|
| `verdict=CLI_ERROR` | `python -m falsify` is missing or the spawn failed. Install the public CLI. |
| `verdict=L2_CLEAN` | Static lint only. Do not ship on this. |
| `verdict=PASS` from `falsify_review` | Epistemic document PASS. Still `claim_bearing=false`. |
| `production` / `quant` gate BLOCKs | Expected on the public CLI. Pro adapters are closed. |
| Plugin listed but tools missing | Profile did not load `dsh.bundle.patch`. Reinstall and restart. |

Logs: the tool result includes `stdout`, `stderr`, `command`, and `exit_code`. Rollback = uninstall the plugin.

## Community and support

- Official site: [https://falsify.site/](https://falsify.site/)
- File issues on [shi275773124/falsify-dsh](https://github.com/shi275773124/falsify-dsh/issues).
- The plugin is listed under the [`dsh-plugin`](https://github.com/topics/dsh-plugin) topic.
- Catalog listing: [awesome-dsh-plugins#8](https://github.com/AdamPlatin123/awesome-dsh-plugins/pull/8) merged 2026-08-13.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Chinese: [CONTRIBUTING.zh.md](CONTRIBUTING.zh.md).

## Development

```sh
npm install
npm test
npm run typecheck
```

`src/cli.ts` is the portable wrapper and is covered by `test/cli.test.mjs`. `src/index.ts` is the Cordis registration surface and is loaded by DSH; it is not unit-tested against unpublished `@deepseek-ai/dsh-tools`.

For agents, follow [AGENTS.md](AGENTS.md).

## Not this plugin

- Not a DSH skin, sidebar, or TUI.
- Not `dsh-inspect`. inspect = find/fix/review loop. Falsify = default-BLOCK adjudicator + receipt.
- Not the closed Pro runtime, HMAC claim-bearing signer, or live venue adapter.
- Tagging the Python monorepo with `dsh-plugin` would be false-green. This adapter is the thing that gets the topic.

## Known limitations

- No frozen DSH SHA runtime proof yet. Static contract + wrapper tests only.
- Public CLI has no `doctor` subcommand. Do not add a fake one here.
- `capital_authority` is always `NONE` on this adapter. That is intentional.

## License

[MIT](LICENSE)

Report security issues privately to the maintainer of [shi275773124/Falsify](https://github.com/shi275773124/Falsify). Do not file public issues that include keys, receipts with secrets, or live account paths.