Skip to content

Commit 205d4e0

Browse files
phodalQoder-AI
phodal
and
Qoder-AI
committed
feat(docs): add docusaurus site with zh-Hans i18n and pages deploy
Add a Docusaurus documentation site under docs/ with English docs, zh-Hans translations, a landing page, and asset sync script. Add a GitHub Pages deploy workflow, docs-site contract tests, and extend npm-package bundle/verify scripts plus doc-link-graph routing to exclude the site build. Validated with npm test (860 pass). Spec: docs/specs/2026-07-28-docusaurus-site-demo-pages.md Co-authored-by: QoderAI (Qwen 3.8 Max) <qoder_ai@qoder.com>
1 parent 1ad9642 commit 205d4e0

40 files changed

Lines changed: 21179 additions & 3 deletions

‎.github/workflows/pages.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: Deploy Website
2+
3+
on:
4+
push:
5+
branches: [main]
6+
paths:
7+
- "docs/**"
8+
- "assets/**"
9+
- ".github/workflows/pages.yml"
10+
workflow_dispatch:
11+
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
concurrency:
18+
group: pages
19+
cancel-in-progress: false
20+
21+
jobs:
22+
build:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- uses: actions/checkout@v4
26+
- uses: actions/setup-node@v4
27+
with:
28+
node-version: 24
29+
cache: npm
30+
cache-dependency-path: docs/package-lock.json
31+
- name: Install website dependencies
32+
run: npm ci
33+
working-directory: docs
34+
- name: Build website
35+
run: npm run build
36+
working-directory: docs
37+
- uses: actions/configure-pages@v5
38+
- uses: actions/upload-pages-artifact@v3
39+
with:
40+
path: docs/build
41+
42+
deploy:
43+
needs: build
44+
runs-on: ubuntu-latest
45+
environment:
46+
name: github-pages
47+
url: ${{ steps.deployment.outputs.page_url }}
48+
steps:
49+
- id: deployment
50+
uses: actions/deploy-pages@v4

‎README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
</p>
2121

2222
<p align="center">
23+
<a href="https://qoderai.github.io/better-harness/">Website</a> ·
2324
<a href="#quick-start">Quick Start</a> ·
2425
<a href="#see-it-in-action">Demo</a> ·
2526
<a href="#why-better-harness">Why</a> ·
@@ -44,11 +45,12 @@ prioritized findings with an impact, expected output, scoped repair, and
4445
acceptance checks.
4546

4647
<p align="center">
47-
<a href="assets/demo/better-harness-report.html"><img src="assets/demo/better-harness-findings-report.png" alt="Better Harness HTML report showing an evidence-bounded finding with its impact, expected output, scoped AI fix, and acceptance checks" width="900"></a>
48+
<a href="https://qoderai.github.io/better-harness/demo/better-harness-report/"><img src="assets/demo/better-harness-findings-report.png" alt="Better Harness HTML report showing an evidence-bounded finding with its impact, expected output, scoped AI fix, and acceptance checks" width="900"></a>
4849
</p>
4950

5051
<p align="center">
51-
<sub><a href="assets/demo/better-harness-report.html">Open the complete self-contained English HTML report</a>.</sub>
52+
<sub><a href="https://qoderai.github.io/better-harness/demo/better-harness-report/">Open the complete self-contained English HTML report</a>
53+
(<a href="assets/demo/better-harness-report.html">source</a>).</sub>
5254
</p>
5355

5456
After you have comparable reports over time, the history view shows how the five

‎docs/.gitignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Docusaurus
2+
build/
3+
.docusaurus/
4+
node_modules/
5+
6+
# Synced from ../assets/ by scripts/sync-assets.mjs
7+
static/demo/
8+
static/img/agent-work-loop-en.svg
9+
static/img/better-harness-architecture-en.svg
10+
static/img/codex-add-marketplace.jpg

‎docs/docs/concepts/agent-work-loop.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
id: agent-work-loop
3+
title: Agent Work Loop
4+
sidebar_position: 1
5+
---
6+
7+
# Agent Work Loop
8+
9+
The **Agent Work Loop** reviews whether a coding-agent Harness can carry one
10+
task from a clear intent to a validated, reliably delivered result, then turn
11+
supported learning opportunities into improvements that remain useful over
12+
time. It is not a mandatory process, transcript score, asset inventory, or
13+
repository maturity model.
14+
15+
![Agent Work Loop: five dimensions from task understanding through learning capture](/img/agent-work-loop-en.svg)
16+
17+
## The loop being scored
18+
19+
A good harness lets an agent finish a bounded, recoverable loop:
20+
21+
```text
22+
understand context -> make a bounded change -> choose the right validation ->
23+
interpret failure -> repair -> re-run validation -> state residual risk
24+
```
25+
26+
## The five dimensions
27+
28+
| Dimension | The question it answers | Backed by |
29+
| --- | --- | --- |
30+
| **Task Understanding** | Does the agent know the goal and what "done" means? | Rules, `AGENTS.md`, specs, `DESIGN.md` |
31+
| **Controlled Execution** | Is the work on supported, repeatable paths? | Skills, commands, MCP tools, sandbox boundaries |
32+
| **Change Validation** | Is there evidence the change actually works? | Tests, lint, Hooks, observable diagnostics |
33+
| **Reliable Delivery** | Does AI speed bypass quality checks or acceptance? | Human review, approvals, CI/CD, recovery paths |
34+
| **Learning Capture** | Does the next task benefit from this one? | Loop Discovery, reusable SDLC Skills, Memory |
35+
36+
Each dimension resolves three stable checks (fifteen check ids in total)
37+
before it is scored. Learning Capture is scored independently of the first
38+
four dimensions.
39+
40+
## Review unit: the Task Episode
41+
42+
A **Task Episode** is one user goal with one acceptance boundary. It may span
43+
multiple turns or sessions, but every claim must stay tied to the same goal,
44+
target, action, and result. Unrelated work is never merged because it happened
45+
in one session, and aggregate counts never become task behavior.
46+
47+
When eligible session evidence is partial or unavailable, the review stays a
48+
`session-limited` Agent Work Loop review: unavailable behavior remains
49+
`Unobserved`, and inspected project Harness evidence supports only the
50+
mechanisms it can support.
51+
52+
## Evidence states
53+
54+
- `Present`: an owned mechanism or review contract exists;
55+
- `Wired`: the relevant task, trigger, or owner route can reach it;
56+
- `Exercised`: a linked episode or inspection used it and retained a result;
57+
- `Outcome-supported`: a comparable later result supports the claimed effect;
58+
- `Missing`: inspected evidence confirms a required mechanism or result is absent;
59+
- `Unobserved`: the available observation boundary cannot decide;
60+
- `Not applicable`: inspected task and project evidence proves it does not apply.
61+
62+
Evidence state is not pass/fail. An exercised operation may expose a defect, a
63+
safe denial may be correct behavior, and an unavailable external boundary is
64+
`Unobserved`, not automatically `Missing`.
65+
66+
## Evidence limits score confidence
67+
68+
For the four current-task dimensions, the highest supported evidence state
69+
sets an absolute score ceiling:
70+
71+
| Highest supported evidence | Absolute score ceiling |
72+
| --- | --- |
73+
| `Missing`, `Unobserved`, or `Not applicable` | 59 |
74+
| `Present` | 74 |
75+
| `Wired` | 84 |
76+
| `Exercised` | 94 |
77+
| `Outcome-supported` | 100 |
78+
79+
These are ceilings, not a score formula. A configured capability is not
80+
observed use, and only an `Outcome-supported` later comparison permits a claim
81+
that an intervention improved later work.
82+
83+
## Full model
84+
85+
The complete contract — check tables, findings, scoring boundaries, and
86+
longitudinal validation — lives in
87+
[`models/agent-work-loop.md`](https://github.com/QoderAI/better-harness/blob/main/models/agent-work-loop.md).

‎docs/docs/concepts/findings-and-evidence.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
---
2+
id: findings-and-evidence
3+
title: Findings & Evidence
4+
sidebar_position: 2
5+
---
6+
7+
# Findings & Evidence
8+
9+
Better Harness is deliberately honest: every claim in a report is bounded by
10+
what was actually observed. This page explains the boundaries that make a
11+
report trustworthy.
12+
13+
## The evidence boundary
14+
15+
Three evidence domains stay independent until unified analysis:
16+
17+
- **Session evidence** — what agents actually did in relevant Task Episodes,
18+
where the host supports a real local session source.
19+
- **Project evidence** — repository mechanisms: instructions, validation,
20+
hooks, delivery gates, and reusable knowledge routes.
21+
- **Agent assets** — configured Skills, commands, rules, MCP tools, and
22+
instruction files.
23+
24+
The shared boundary across all three: **configured assets can establish that a
25+
mechanism exists, but only linked task evidence can establish that it was used
26+
or improved an outcome.**
27+
28+
## What a finding contains
29+
30+
Each finding turns one supported gap into an actionable row:
31+
32+
- **Impact** — why the gap matters for the work loop;
33+
- **Evidence** — the visible source the finding is bounded by;
34+
- **Expected output** — what "fixed" looks like;
35+
- **Scoped repair** — a bounded fix plan draft for review;
36+
- **Acceptance checks** — how to validate the repair landed.
37+
38+
Missing or partial evidence stays explicit in the report instead of becoming
39+
an unsupported score or claim.
40+
41+
## The project lens: five software capabilities
42+
43+
Alongside the task-centered Agent Work Loop, the independent project-evidence
44+
pass uses a static lens:
45+
46+
| Capability | Question it answers |
47+
| --- | --- |
48+
| Context Map | Can the agent find the right context, boundary, risk area, and next step? |
49+
| Environment Readiness | Can the project set up, run, reset, and diagnose without guesswork? |
50+
| Fast Feedback | Do relevant checks return useful feedback quickly after a change? |
51+
| Quality Gates | Are architecture, security, schema, migration, and drift rules enforced? |
52+
| Change Safety | Are risky actions, acceptance, and recovery controlled? |
53+
54+
Unobserved task behaviour is never treated as missing repository capability.
55+
56+
## Confidence
57+
58+
Reports rate confidence Low/Medium/High, bound to how much was actually
59+
executed versus only read. Static-only first passes stay Low/Medium; passing a
60+
current check proves the intervention was exercised, and only a comparable
61+
later result can prove the loop improved.
62+
63+
## Going deeper
64+
65+
- One-page overview:
66+
[`docs/concepts.md`](https://github.com/QoderAI/better-harness/blob/main/docs/concepts.md)
67+
- Model routing and advanced lenses:
68+
[`models/routing.md`](https://github.com/QoderAI/better-harness/blob/main/models/routing.md)

‎docs/docs/concepts/glossary.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
id: glossary
3+
title: Glossary
4+
sidebar_position: 3
5+
---
6+
7+
# Glossary
8+
9+
A one-stop decoder for the vocabulary in reports and docs. You only need two
10+
terms to start: **lifecycle dimensions** and **report**. Everything below is
11+
progressive detail you load when a task needs it.
12+
13+
## The mental model in three lines
14+
15+
- A **harness** wraps a target so an agent can run a bounded, recoverable
16+
loop: understand → change → validate → repair → re-validate → state residual
17+
risk.
18+
- Better Harness starts from the Agent Work Loop, qualifies it with available
19+
session and project evidence, guards changes while they happen, and feeds
20+
what it learns back into rules.
21+
- Session evidence changes confidence and coverage, not the model.
22+
23+
## Core concepts
24+
25+
| Term | What it means |
26+
| --- | --- |
27+
| Harness | The engineering environment around an agent that makes a change loop bounded and recoverable. |
28+
| The loop | `understand context -> bounded change -> choose validation -> interpret failure -> repair -> re-run validation -> state residual risk` |
29+
| Agent Work Loop | The default `/better-harness` model: what the Harness supports, what agents actually did when observable, where a task loop lost control, and what should improve next. |
30+
| Task Episode | One user goal with one acceptance boundary; the review unit for behavior claims. |
31+
| Software Fluency | The static project lens used for an explicit repository-only score and the independent project evidence pass. |
32+
| Progressive disclosure | Reveal context to an agent by task, not all at once. |
33+
34+
## Lenses and models
35+
36+
| Term | What it means |
37+
| --- | --- |
38+
| Five lifecycle dimensions | Task Understanding, Controlled Execution, Change Validation, Reliable Delivery, Learning Capture. |
39+
| Five software capabilities | Context Map, Environment Readiness, Fast Feedback, Quality Gates, Change Safety. |
40+
| AI Readiness Ladder | The L1–L5 maturity scale (Awareness → Assisted → Structured → Spec-Governed → Closed-Loop). |
41+
| Style | The visual framing of a report (analyst, audit scorecard, consulting deck, dashboard, …). |
42+
| Output mode | The rendered form of a report: Qoder Canvas, HTML visual, or Markdown. |
43+
44+
## Evidence and scoring
45+
46+
| Term | What it means |
47+
| --- | --- |
48+
| Evidence boundary | The rule that separates static file evidence from executed command, CI, runtime, or UI evidence; unverified areas cap confidence. |
49+
| Evidence state | `Present`, `Wired`, `Exercised`, `Outcome-supported`, `Missing`, `Unobserved`, or `Not applicable` — see [Agent Work Loop](./agent-work-loop.md). |
50+
| Confidence | Low/Medium/High rating bound to how much was actually executed vs. only read. |
51+
| Change confidence | Whether an AI-generated change is ready to land, judged by blast radius, sensitive paths, size, and validation. |
52+
53+
## The action loop (report → change)
54+
55+
| Term | What it means |
56+
| --- | --- |
57+
| Handoff | A row-scoped next step inside a report (draft a fix, schedule a follow-up), not a dead-end score. |
58+
| Repair plan | A bounded fix plan for one finding, drafted via `/better-harness repair-plan` without writing report artifacts. |
59+
| Loop Engineering | The domain that decides whether repeated work exists and which durable owner (skill, hook, script, automation, rule) should hold it. |
60+
| Loop Discovery | The routing gate that proves a loop from evidence and picks the smallest durable owner. |
61+
| Schedule-ready | A finding stable enough to become a recurring `/schedule /better-harness` follow-up, with cadence, validation, and a stop condition. |
62+
63+
## Extension and hosting
64+
65+
| Term | What it means |
66+
| --- | --- |
67+
| Skill | A repeatable agent workflow defined by `SKILL.md` frontmatter plus a concise workflow. |
68+
| Host adapter | Per-host discovery and evidence-shape glue; keeps the engine host-neutral. |
69+
| Host shell | Thin host metadata (`.claude-plugin/`, `.qoder-plugin/`, `.cursor-plugin/`, `.codex-plugin/`) that exposes canonical behavior without owning product logic. |
70+
| Canonical owner | The single directory that owns a behavior's product judgment; host shells and mirrors point back to it. |
71+
72+
The full glossary with owner links lives in
73+
[`docs/glossary.md`](https://github.com/QoderAI/better-harness/blob/main/docs/glossary.md).

‎docs/docs/hosts/adapter-matrix.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
id: adapter-matrix
3+
title: Adapter Matrix
4+
sidebar_position: 1
5+
---
6+
7+
# Host Adapter Matrix
8+
9+
Better Harness runs inside your existing coding agent. Host differences enter
10+
only a thin adapter layer: host shells, configured-asset providers, session
11+
evidence adapters, and output modes. Canonical product judgment stays
12+
host-neutral.
13+
14+
## Hosts at a glance
15+
16+
| Host | Positioning | Shell | Session Evidence | Default Output |
17+
| --- | --- | --- | --- | --- |
18+
| Qoder | First-class product host | `.qoder-plugin/` | Qoder sessions | Qoder Canvas report |
19+
| Claude Code | Analysis-capable source-local host | `.claude-plugin/` | Workspace-matching local Claude transcripts when present | Self-contained HTML + Markdown |
20+
| Codex | Analysis-capable source-local host | `.codex-plugin/` | Codex sessions | Self-contained HTML + Markdown |
21+
| Cursor | Analysis-capable source-local host | `.cursor-plugin/` | Workspace-matched transcripts, metadata, and audit logs; partial coverage stays explicit | Self-contained HTML + Markdown |
22+
23+
The `@qoderai/better-harness` npm package includes all four plugin metadata
24+
roots. The generated Qoder runtime bundle includes only the Qoder shell;
25+
non-Qoder generated host artifacts remain source-local.
26+
27+
## Output modes
28+
29+
- **Qoder Canvas** — renderer-owned `findings.json`, Canvas-only
30+
`canvas.json`, and `report.canvas.tsx`.
31+
- **HTML visual** — portable Claude Code/Codex/Cursor contract covering
32+
`findings.json`, `report.md`, and a self-contained `report.html`
33+
(see the [live demo](pathname:///demo/better-harness-report/)).
34+
- **Markdown-only** — no visual companion.
35+
36+
## Capability coverage
37+
38+
Capabilities differ per host on purpose: no host claims a capability without a
39+
real evidence source, and unsupported behavior fails before reading private
40+
data or changing files. The maintained capability-by-capability coverage
41+
table, TODO list, and definition of done live in the repository
42+
[roadmap](https://github.com/QoderAI/better-harness/blob/main/roadmap.md).
43+
44+
## Source of truth
45+
46+
The canonical matrix, discovery rules, and split triggers live in
47+
[`docs/adapters/README.md`](https://github.com/QoderAI/better-harness/blob/main/docs/adapters/README.md).

0 commit comments

Comments
 (0)