Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,8 @@ jobs:
- run: npm ci
- name: Run native DSH Skill discovery smoke
run: npm run test:dsh-native
- name: Run native DSH configured-assets smoke
run: npm run test:dsh-configured-assets-native
- name: Run Vitest
run: npm run test:ci
- name: Verify Harness DSL generated sources
Expand Down
34 changes: 23 additions & 11 deletions docs/adapters/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

This is the single entry point for Claude Code, Codex, Qoder, Cursor, Qwen,
GitHub Copilot, Pi, Kimi Code, WorkBuddy, and Grok host boundaries, plus the
DeepSeek Harness (DSH) verified install/discovery and developer-preview session
slices. Do not
DeepSeek Harness (DSH) verified install/discovery, developer-preview
configured-assets, and developer-preview session slices. Do not
create `docs/adapters/claude-code.md`, `docs/adapters/codex.md`,
`docs/adapters/qoder.md`, `docs/adapters/cursor.md`, `docs/adapters/qwen.md`,
`docs/adapters/copilot.md`, `docs/adapters/pi.md`,
Expand Down Expand Up @@ -45,7 +45,7 @@ project `.kimi-code/skills/`), then runs `/skill:better-harness`.
| Kimi Code | Analysis-capable source-local host | `.kimi-plugin/plugin.json` | `scripts/agent-customize/providers/kimi.mjs` | `scripts/session-analysis/platforms/kimi.mjs` | self-contained HTML + Markdown | `AGENTS.md` + `~/.kimi-code/skills` + project `.kimi-code/skills`/`.kimi/skills` + `~/.kimi-code/mcp.json` | `harness evidence-bundle --platform kimi` -> validated `html` render |
| WorkBuddy | Analysis-capable source-local host | none (skills install into `~/.workbuddy/skills`) | `scripts/agent-customize/providers/workbuddy.mjs` | `scripts/session-analysis/platforms/workbuddy.mjs` | self-contained HTML + Markdown | `~/.workbuddy` `AGENTS.md` + identity files + `.agents` + `AGENTS.md` | `session-analysis --platform workbuddy sources` -> validated `html` render |
| Grok | Analysis-capable source-local host | none (skills install into `~/.grok/skills`) | `scripts/agent-customize/providers/grok.mjs` | `scripts/session-analysis/platforms/grok.mjs` | self-contained HTML + Markdown | `~/.grok` + `.grok` + `.agents` + `AGENTS.md` | `session-analysis --platform grok sources` -> skill symlink -> validated `html` render |
| DeepSeek Harness (DSH) | Verified install/discovery for headless/base and Web `standard`/`code`/`cordis`; partial session evidence (developer preview) | local DSH Cordis policy at `scripts/dsh-skill-discovery/index.mjs`; no lifecycle shell | unavailable | `scripts/session-analysis/platforms/dsh.mjs`; `dsh-v1` for the audited format-0 session-evidence slice from DSH `dsh-v0.1.0-rc.7` and `dsh-v0.1.0-rc.8`, raw `.jsonl` and feature-detected `.jsonl.zstd` | unavailable; no report route | canonical Skill from the complete root; model Skill calls rejected | `npm run test:dsh-native`; read-only session `sources`/`facts` commands remain separate |
| DeepSeek Harness (DSH) | Verified install/discovery for headless/base and Web `standard`/`code`/`cordis`; partial configured assets and session evidence (developer preview) | local DSH Cordis policy at `scripts/dsh-skill-discovery/index.mjs`; no lifecycle shell | `scripts/agent-customize/providers/dsh.mjs`; filesystem Skills and cwd-sensitive Instructions, configured-not-observed | `scripts/session-analysis/platforms/dsh.mjs`; `dsh-v1` for the audited format-0 session-evidence slice from DSH `dsh-v0.1.0-rc.7` and `dsh-v0.1.0-rc.8`, raw `.jsonl` and feature-detected `.jsonl.zstd` | unavailable; no report route | canonical Skill from the complete root; model Skill calls rejected | `npm run test:dsh-native`; `npm run test:dsh-configured-assets-native`; read-only session `sources`/`facts` commands remain separate |

## Read-only Plugin Lifecycle

Expand Down Expand Up @@ -86,8 +86,8 @@ Kimi Code, Grok, and DSH are absent from this table on purpose: none has a
validated native lifecycle contract yet, so lifecycle targets reject them with
`UNKNOWN_HOST` instead of borrowing another host's install route. Kimi Code and
Grok retain their configured-asset and session evidence. DSH retains its
bounded verified discovery and partial session-evidence slices, but has no
lifecycle profile or native lifecycle claim.
bounded verified discovery, configured-assets, and partial session-evidence
slices, but has no lifecycle profile or native lifecycle claim.

The lifecycle commands do not read raw session transcripts, contact a registry,
edit host settings, or register an `apply` path.
Expand Down Expand Up @@ -193,7 +193,7 @@ edit host settings, or register an `apply` path.
`signals.json`). The adapter honors `GROK_HOME`. Grok has no install shell in
this repository; skills install manually into `~/.grok/skills` (symlink is
enough for `/better-harness`).
- DeepSeek Harness has two independent bounded slices. Verified
- DeepSeek Harness has independent bounded capabilities. Verified
install/discovery uses DSH `0.1.1-rc.2` at audited source
`b150a551b8d465e31e418e1b2eaf5e79bbb7d28e`. The sole supported discovery
route points the active DSH `skill-filesystem.customSkillDirs` at the
Expand All @@ -213,6 +213,18 @@ edit host settings, or register an `apply` path.
values are not canonical routes. Moving the Better Harness root requires
updating every configured absolute path. The credential-free native owner
smoke is `npm run test:dsh-native`.
- Its developer-preview configured-assets provider at
`scripts/agent-customize/providers/dsh.mjs` reports native filesystem Skill
winners and byte-budget-represented Instruction sources for an authorized
workspace and cwd. User-home sources are excluded unless
`--include-user-home` is supplied. The evidence is
`configured-not-observed`: runtime/in-process Skills and active Cordis,
Profile, and Preset composition remain unresolved. DSH advertises exactly
`sessionAnalysis` and `agentCustomize`; it does not gain asset-practices,
checkup, evidence-bundle, report, rendering, or output support. See
[DeepSeek Harness Configured Assets](../../references/agent-customize/platforms/dsh.md)
and run the credential-free owner smoke with
`npm run test:dsh-configured-assets-native`.
- Separately, DeepSeek Harness has a developer-preview, JSONL-only session
adapter at `scripts/session-analysis/platforms/dsh.mjs`. Home resolution is strictly
`--dsh-home` over `DSH_HOME` over `~/.dsh`, and the only source root is
Expand All @@ -222,9 +234,8 @@ edit host settings, or register an `apply` path.
workspace evidence. Better Harness reports adapter metadata `dsh-v1`; its
format-0 session-evidence slice is validated against `dsh-v0.1.0-rc.7` and
`dsh-v0.1.0-rc.8`, including RC8 interrupted assistant messages and the
required team-event vocabulary. The host is registered only for the
`sessionAnalysis` capability; team events are validated and accounted, not
projected as team analytics.
required team-event vocabulary. Team events are validated and accounted,
not projected as team analytics.
Known-but-unsupported events and unknown ignorable events are explicitly
accounted for. Unknown required events, malformed records, identity drift,
committed corruption, and unsupported versions fail closed; an uncommitted
Expand All @@ -238,8 +249,9 @@ edit host settings, or register an `apply` path.
compressed evidence is unavailable while independent raw JSONL evidence
remains readable. There is no fallback dependency or shell.
The combined DSH boundary does not provide live PTY or process state,
configured assets, plugin lifecycle, a managed shell, manifest or package
integration, report/output routing, README Quickstart, SQLite or custom
complete runtime configured-asset resolution, plugin lifecycle, a managed
shell, manifest or package integration, report/output routing, README
Quickstart, SQLite or custom
persistence, automatic optimization, plugin fault or causality attribution,
or artifact repair or writes. See
[Story #93](https://github.com/QoderAI/better-harness/issues/93)
Expand Down
35 changes: 26 additions & 9 deletions docs/docs/hosts/adapter-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,14 @@ host-neutral.
## Support levels

Better Harness currently declares ten more complete capability-level host
adapters plus bounded DSH discovery and session slices. Six have verified public
adapters plus bounded DSH discovery, configured-assets, and session slices. Six
have verified public
Quickstart paths. Pi, Kimi Code, WorkBuddy, and Grok are visible as adapter
support because their installation and end-to-end evidence boundaries differ
from that six-host set. DSH has Verified install/discovery for a qualified
runtime/preset boundary plus a developer-preview session-evidence contract; it
is not a runnable report adapter. The [canonical adapter matrix](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/README.md)
runtime/preset boundary plus developer-preview configured-assets and
session-evidence contracts; it is not a runnable report adapter. The
[canonical adapter matrix](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/README.md)
remains the complete capability-level source of truth.

## Supported host adapters
Expand All @@ -36,7 +38,7 @@ remains the complete capability-level source of truth.
| Kimi Code | Adapter support | Analysis-capable source-local host | `.kimi-plugin/plugin.json` | Workspace-matching Kimi wire transcripts | Self-contained HTML + Markdown |
| WorkBuddy | Adapter support | Analysis-capable source-local host | None; skills use WorkBuddy-owned paths | Workspace-matching WorkBuddy JSONL transcripts | Self-contained HTML + Markdown |
| Grok | Adapter support | Analysis-capable source-local host | None; skills use Grok-owned paths | Workspace-matching Grok session dirs (`updates.jsonl`) | Self-contained HTML + Markdown |
| DeepSeek Harness (DSH) | Verified install/discovery | Qualified headless/base and Web `standard`/`code`/`cordis`; partial session evidence | Local DSH Cordis policy; no lifecycle shell | DSH JSONL backend session format `0`: raw `.jsonl` and feature-detected `.jsonl.zstd` | Unavailable |
| DeepSeek Harness (DSH) | Verified install/discovery | Qualified headless/base and Web `standard`/`code`/`cordis`; partial configured-assets and session evidence | Local DSH Cordis policy; no lifecycle shell | DSH JSONL backend session format `0`: raw `.jsonl` and feature-detected `.jsonl.zstd` | Unavailable |

The `@qoder-ai/better-harness` npm package includes all seven plugin metadata
roots. Pi reuses install metadata in the existing `package.json`, so it does
Expand Down Expand Up @@ -145,6 +147,22 @@ Harness root requires reconfiguring every absolute path. The Installation page
documents the configuration boundary; run the pinned, credential-free owner
smoke with `npm run test:dsh-native`.

DSH also has a developer-preview configured-assets provider. It reports native
filesystem Skill winners and cwd-sensitive Instruction sources as
configured-not-observed evidence:

```bash
better-harness agent-customize inventory --provider dsh --workspace <path> [--cwd <path>] [--dsh-home <dir>] [--include-user-home[=true]]
```

User-home Skills and Instructions are not read by default. Runtime/in-process
Skills and active Cordis, Profile, and Preset composition remain unresolved.
The host advertises exactly `sessionAnalysis` and `agentCustomize`; this does
not add asset-practices, evidence-bundle, report, rendering, or output support.
Repository contributors can run the pinned credential-free comparison with
`npm run test:dsh-configured-assets-native`. See
[DeepSeek Harness Configured Assets](https://github.com/QoderAI/better-harness/blob/main/references/agent-customize/platforms/dsh.md).

Separately, DSH has a developer-preview JSONL session slice with Better Harness
adapter metadata `dsh-v1`. Its format-0 session-evidence slice is
validated against DSH `dsh-v0.1.0-rc.7` and `dsh-v0.1.0-rc.8`, including RC8
Expand All @@ -153,8 +171,7 @@ are validated and accounted, not projected as team analytics. Home resolution
is strictly `--dsh-home` over `DSH_HOME` over `~/.dsh`; the only source root is
`<home>/sessions`. The adapter reads the fixed nested `session.jsonl` or
`session.jsonl.zstd` layout without writing or repairing artifacts, and it
qualifies a workspace only from the header's absolute `cwd`. DSH is registered
only for the `sessionAnalysis` capability.
qualifies a workspace only from the header's absolute `cwd`.

Compressed artifacts are concatenated independently checksummed Zstandard
frames and are validated and decompressed one complete frame at a time. The
Expand All @@ -176,9 +193,9 @@ node scripts/session-analysis.mjs sources --platform dsh --workspace <path> [--d
```

Verified discovery does not imply a complete report loop. DSH has no live
PTY/process integration, configured-assets support, plugin lifecycle, managed
shell, manifest, package integration, report/output route, public Quickstart,
SQLite or custom persistence support, automatic
PTY/process integration, complete runtime configured-asset resolution, plugin
lifecycle, managed shell, manifest, package integration, report/output route,
public Quickstart, SQLite or custom persistence support, automatic
optimization, plugin-fault attribution, or artifact mutation/recovery. See the
[canonical source matrix](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/README.md)
and [Story #93](https://github.com/QoderAI/better-harness/issues/93).
Expand Down
28 changes: 24 additions & 4 deletions docs/docs/installation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -134,16 +134,36 @@ Better Harness root moves, update both the `customSkillDirs` value and policy
plugin path/configuration. Repository contributors can repeat the pinned,
credential-free native proof with `npm run test:dsh-native`.

This maturity level does not provide configured assets, evidence-bundle or
report registration, output routing, rendering, lifecycle management,
MCP/profile product support, Web `minimal`, or a full report workflow. The
### Inventory configured assets

The independent developer-preview configured-assets provider reports native
filesystem Skill winners and cwd-sensitive Instruction sources as
configured-not-observed evidence:

```bash
better-harness agent-customize inventory --provider dsh --workspace <path> [--cwd <path>] [--dsh-home <path>] [--include-user-home[=true]]
```

The default excludes user-home DSH and Agents roots. Add
`--include-user-home` only when those sources are intentionally in scope.
Runtime/in-process Skills and active Cordis, Profile, and Preset composition
remain unresolved, so the inventory does not prove that any asset was used.
Repository contributors can repeat the pinned, credential-free native
comparison with `npm run test:dsh-configured-assets-native`. The complete
configured-assets boundary is documented in the
[adapter matrix](./hosts/adapter-matrix#deepseek-harness-dsh).

This maturity level does not provide complete runtime configured-asset
resolution, evidence-bundle or report registration, output routing, rendering,
lifecycle management, MCP/profile product support, Web `minimal`, or a full
report workflow. The
[adapter matrix](./hosts/adapter-matrix#deepseek-harness-dsh) tracks the exact
boundary.

:::tip Don't see your Coding Agent?

The six tabs below are the verified Quickstart paths, while the project tracks
ten fuller host adapters plus bounded DSH slices. [Compare all adapter support boundaries](./hosts/adapter-matrix),
ten fuller host adapters plus bounded DSH capabilities. [Compare all adapter support boundaries](./hosts/adapter-matrix),
then [follow the new-host contribution workflow and worked pull requests](./hosts/contributing-new-coding-agent)
if you want to add or complete an integration. You can also
[browse current repository pull requests](https://github.com/QoderAI/better-harness/pulls)
Expand Down
14 changes: 7 additions & 7 deletions docs/specs/2026-08-19-67-antigravity-plugin-artifact.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,8 +108,8 @@ The generated root basename is `better-harness`. Its positive allowlist is:
- `scripts/**` except `scripts/packaging/**`;
- `references/**`, `templates/**`, `models/**`, `hooks/**`, `docs/**`, and
`case-studies/**`;
- `node_modules/@vscode/tree-sitter-wasm/**` and
`node_modules/esbuild-wasm/**`, including package metadata and licenses.
- `node_modules/@vscode/tree-sitter-wasm/**`, `node_modules/esbuild-wasm/**`,
and `node_modules/yaml/**`, including package metadata and licenses.

The builder copies only regular files and directories reached without following
symbolic links. The verifier rejects unknown roots, other Skills and host
Expand All @@ -125,8 +125,8 @@ and `dependencies`. It binds:
`module`;
- `bin` to the singleton `{ "better-harness": "scripts/better-harness.mjs" }`;
- `engines` to exact nonblank `node` and `npm` entries projected from source;
- `dependencies` to exact version-bound `@vscode/tree-sitter-wasm` and
`esbuild-wasm` entries.
- `dependencies` to exact version-bound `@vscode/tree-sitter-wasm`,
`esbuild-wasm`, and `yaml` entries.

The builder projects fresh nested objects and rejects missing, extra, blank,
non-string, or wrong source runtime metadata rather than aliasing source
Expand All @@ -145,10 +145,10 @@ Repository-only navigation uses absolute upstream HTTPS URLs and is not copied
or traversed. `pathname:` is treated only as a non-local Docusaurus route;
`file:` and unknown schemes fail closed.

The verified pinned artifact contains a Markdown closure of exactly 93 nodes,
290 edges, and 96 files. Runtime analysis starts at
The verified pinned artifact contains a Markdown closure of exactly 106 nodes,
305 edges, and 109 files. Runtime analysis starts at
`scripts/better-harness.mjs` and proves a syntax-aware ESM closure of 19 modules
and 39 edges, plus the exact two packaged dependencies and their licenses.
and 39 edges, plus the exact three packaged dependencies and their licenses.
Limits bound files, bytes, depth, nodes, and edges.

Three target-only source-integrity repair groups make that shipped closure
Expand Down
Loading