fix(templates): route WorkBuddy to the portable HTML report by creayma-del · Pull Request #31 · QoderAI/better-harness

creayma-del · 2026-07-31T03:07:57Z

The WorkBuddy host adapter shipped claiming self-contained HTML + Markdown
output in the adapter matrix, docs site, and CHANGELOG 0.4.0, but
templates/reporting/routing.md never listed WorkBuddy in the Portable HTML
report route, so agents on WorkBuddy were never routed to the shipped output.

Summary

Agents running on the WorkBuddy host are now routed to the shipped
self-contained HTML + Markdown report output. A new derived
support-declaration check makes it impossible to add a matrix host claiming
portable HTML output without listing it in the report routing row.

Why

Issue/Story: none; justified maintenance — follow-up to the WorkBuddy host
adapter (4b871d9, CHANGELOG 0.4.0), which claims portable HTML routing
is implemented while the routing switchboard never listed WorkBuddy.
User or maintainer outcome: WorkBuddy users get the portable HTML report
the matrix and docs already promise; maintainers get a consistency test
that catches this class of omission for every future host.

Traceability and Scope

Spec/ADR, if applicable: docs/specs/2026-07-30-routing-workbuddy-host.md
Acceptance criteria addressed: AC-1 (routing row lists WorkBuddy), AC-2
(both hard-coded assertions updated), AC-3 (derived one-directional
matrix-to-routing check), AC-4 (full suite and doc-link-graph pass)
Canonical owners changed: templates/reporting/routing.md (report
routing switchboard); guarding tests in test/better-harness-skill.test.mjs,
test/style-templates.test.mjs, test/support-declarations.test.mjs;
CHANGELOG.md Unreleased entry
Explicit non-goals: no change to the Cursor entries (the Cursor
durable-report gap stays tracked by the in-flight A-05 PR and roadmap
HA-03); no new WorkBuddy capability, output mode, or renderer change

Change Type

Test and Review Evidence

Check	Result
Red-green proof: `node --test test/support-declarations.test.mjs` with the old `routing.md` restored	Fails as intended: `Portable HTML report route is missing matrix HTML host: WorkBuddy`
`node --test test/support-declarations.test.mjs` (with fix)	7/7 pass
Exact-entry regression (`WorkBuddy` vs `WorkBuddy Enterprise`)	Prefix collision correctly reports `WorkBuddy` as missing; focused routing/docs suite 31/31 pass
`node --test test/better-harness-skill.test.mjs`	12/12 pass
`node --test test/style-templates.test.mjs`	pass
`node --test test/doc-link-graph.test.mjs`	pass; regenerating via `node scripts/doc-link-graph/cli.mjs skills/better-harness` produces zero diff
Full suite: `npm test` (Node 22.20.0 / npm 10.9.3)	1019 pass / 0 fail (net +1 test)
`npm run pack:verify`	pack verification passed: npm 354 entries, runtime zip 377 entries
Merge preview vs in-flight A-05 branch: `git merge-tree`	0 text conflicts; derived check verified to pass against the A-05 matrix (Cursor claim removed) because it is one-directional

Manual or visual evidence: parsed host sets printed and inspected —
htmlHosts resolves to exactly the seven matrix hosts claiming
self-contained HTML + Markdown (Qoder's better-harness output correctly
excluded), and the routing row captures all of them.

Risk and Recovery

Compatibility and cross-platform impact: none; a one-line Markdown routing
change plus test updates. No runtime code changed.
Package, plugin, schema, or generated-file impact: templates/ ships in
the npm package, so the published routing table gains WorkBuddy;
npm run pack:verify passes. No schema or generated files change;
doc-link graph regenerated with zero diff.
Rollback or recovery path: revert the three commits (ef16c6b, 55d44cc,
4cddf91); no data or state migration involved.
Residual risk or unverified boundary: host names are parsed into normalized
route entries and compared exactly, including a prefix-collision regression.
The check remains deliberately one-directional and does not force routing-row
removal when a matrix claim is dropped. No live WorkBuddy runtime smoke was
run; validation is source, fixture, and test evidence.

AI Involvement

Level: Generated
Human review and validation: maintainer reviewed the diff, the red-green
test behavior, the full-suite results, and the pack verification before
push.

Checklist

I followed AGENTS.md, CONTRIBUTING.md, and the relevant canonical-owner guidance.
The change is focused and does not include unrelated local or generated state.
Tests and documentation match the behavior actually delivered.
Markdown links were checked when documentation moved or changed.
Cross-platform behavior was considered for Windows, macOS, and Linux.
Package/runtime verification was run when shipped files or dependencies changed.
User-facing or compatibility changes are recorded in CHANGELOG.md.
I have the right to contribute this work under the repository's MIT License.

The WorkBuddy host adapter shipped claiming self-contained HTML + Markdown output in the adapter matrix, docs site, and CHANGELOG 0.4.0, but templates/reporting/routing.md never listed WorkBuddy in the Portable HTML report route, so agents on WorkBuddy were never routed to the shipped output. Add WorkBuddy to the route, update the two hard-coded host-list assertions, and add a derived support-declaration check so every matrix host claiming portable HTML output must appear in the routing row (one-directional, so a pending durable-report gap can drop the matrix claim first). Spec: docs/specs/2026-07-30-routing-workbuddy-host.md. Validated red-green (the new check fails with 'missing matrix HTML host: WorkBuddy' on the old routing.md) and with the full suite: 1019 pass / 0 fail on Node 22.20.0. Co-authored-by: QoderAI (Qwen 3.8 Max) <qoder_ai@qoder.com>

Add the Unreleased Fixed entry for the routing.md WorkBuddy route and the derived support-declaration check, keeping the PR checklist's CHANGELOG requirement satisfied. Validated with npm test (1019 pass / 0 fail) and npm run pack:verify (354 npm entries, 377 runtime zip entries). Co-authored-by: QoderAI (Qwen 3.8 Max) <qoder_ai@qoder.com>

phodal · 2026-07-31T04:11:22Z

I found one issue worth fixing before merge:

P2 — compare route hosts as exact entries, not substrings

In test/support-declarations.test.mjs, the new guard uses:

routeHosts.includes(host)

This does not prove that the matrix host is actually listed as a distinct route host. I reproduced the false positive by changing the routing row from WorkBuddy to WorkBuddy Enterprise: plain WorkBuddy was no longer an exact route entry, but the derived check still passed. The two hard-coded regex assertions in test/better-harness-skill.test.mjs and test/style-templates.test.mjs also passed the same mutation because they have no trailing boundary.

That leaves AC-3 and the PR's "impossible to omit" claim weaker than stated, and matches the substring risk already called out in the PR description.

Please parse the declared host list into normalized tokens/a set and compare exact values, then add a regression case for a prefix collision such as WorkBuddy vs WorkBuddy Enterprise.

Relevant code:

better-harness/test/support-declarations.test.mjs

Lines 138 to 141 in 55d44cc

    
           const routeHosts = routing.match(/\| Portable HTML report \| Active host is ([^|]+)\|/u)?.[1]; 
        
           assert.ok(routeHosts, "reporting/routing.md does not declare a Portable HTML report route"); 
        
           for (const host of htmlHosts) { 
        
             assert.ok(routeHosts.includes(host), `Portable HTML report route is missing matrix HTML host: ${host}`);

Close the substring-matching hole in the WorkBuddy routing guard so a prefix such as WorkBuddy Enterprise cannot satisfy the WorkBuddy declaration. Tighten the duplicated route assertions and update docs/specs/2026-07-30-routing-workbuddy-host.md with the exact-entry regression contract. Validated with the focused 31-test routing and documentation suite, the full npm test suite on Node 22.20.0, and npm run pack:verify (354 npm entries and 377 runtime ZIP entries). Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>

phodal · 2026-07-31T05:40:34Z

Addressed the exact-entry review gap in 4cddf91: the derived guard now parses normalized route hosts into a set, compares exact values, and includes a WorkBuddy vs WorkBuddy Enterprise prefix-collision regression. The two hard-coded route assertions and the spec were tightened as well.

Validation passed: focused routing/docs suite 31/31, full npm test on Node 22.20.0, npm run pack:verify (354 npm entries / 377 runtime ZIP entries), merge-preview focused suite 31/31 against current main, and all four CI jobs. Squash-merged as 49a2eefc.

creayma and others added 2 commits July 31, 2026 10:18

creayma-del marked this pull request as ready for review July 31, 2026 03:37

phodal merged commit 49a2eef into QoderAI:main Jul 31, 2026
4 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix(templates): route WorkBuddy to the portable HTML report - #31

fix(templates): route WorkBuddy to the portable HTML report#31
phodal merged 3 commits into
QoderAI:mainfrom
creayma-del:fix/routing-workbuddy-host

creayma-del commented Jul 31, 2026 •

edited by phodal

Loading

Uh oh!

phodal commented Jul 31, 2026

Uh oh!

Uh oh!

phodal commented Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

creayma-del commented Jul 31, 2026 • edited by phodal Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Why

Traceability and Scope

Change Type

Test and Review Evidence

Risk and Recovery

AI Involvement

Checklist

Uh oh!

phodal commented Jul 31, 2026

Uh oh!

Uh oh!

phodal commented Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

creayma-del commented Jul 31, 2026 •

edited by phodal

Loading