Skip to content

fix(harness): spell the init hint per tool and scope doctor to cospec files - #63

Merged
replygirl merged 13 commits into
mainfrom
worktree-harness-receipt-and-doctor-scope
Oct 5, 2026
Merged

fix(harness): spell the init hint per tool and scope doctor to cospec files#63
replygirl merged 13 commits into
mainfrom
worktree-harness-receipt-and-doctor-scope

Conversation

@replygirl

@replygirl replygirl commented Oct 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

Two user-visible defects on main, surfaced while reviewing harness-adapter-table
(PR #51), which was held to byte-identical output and could not fix either
(cospec-roadmap ruling 2026-10-04):

  1. The init receipt's closing hint is always spelled for Claude Code.
    cospec init ended every receipt with Try: /cospec:propose … whichever
    harness was selected. /cospec:propose exists only in Claude Code's
    namespaced command dir — wrong for OpenCode (/cospec-propose), and
    meaningless for Codex/agents ($cospec-propose / /cospec-propose), which
    have no slash commands at all.
  2. cospec doctor checks markdown cospec never wrote. Doctor's
    stale-harness, mixed-versions and dangling-ref checks read every .md
    file under a harness dir, not just the files cospec generates — so a user's
    own .claude/notes.md, or a nested worktree checkout under
    .claude/worktrees/, could fail doctor on a healthy repo.

What changes

  • The receipt's two closing hint lines now render through the first selected
    row's body dialect and invocation prefix via the same transformBody that
    renders workflow bodies (claude → /cospec:propose; opencode →
    /cospec-propose; codex/agents → $cospec-propose (Codex) or /cospec-propose (other agents); none keeps today's /cospec:propose).
  • isHarnessDocument is narrowed to exactly two shapes:
    <skills-root>/<skill>/SKILL.md and the table's command paths. Any other
    markdown under a harness dir is no longer a harness document.
  • opsx leftover detection is unchanged: the leftover-scan predicate and walker
    move into init.ts (today's breadth), and doctor's opsx-leftover check now
    reads that same scan.
  • Docs (apps/docs/guide/harness-setup.md, apps/docs/reference/commands.md,
    docs/harness-integration.md) and .agents/shared.md updated to describe
    the corrected behaviour.

Breaking

  • The cospec init receipt for --harness opencode, --harness codex and
    --harness agents (and for any list or detection whose first row is one of
    them) ends with the corrected hint lines. The opencode, codex and
    agents receipt goldens change by design. The claude, all, default and
    none goldens do not change.
  • cospec doctor (text and --json) no longer reports stale-harness,
    mixed-versions or dangling-ref findings for markdown outside
    <skills-root>/<skill>/SKILL.md and the table's command paths. A repo that
    failed doctor only because of such a file now passes, and its findings and
    summary counts shrink. Findings on files cospec writes are unchanged.

Judgment calls

  • The shared-dialect spelling for codex/agents
    ($cospec-propose (Codex) or /cospec-propose (other agents)) is not a
    judgment call made in this PR — cospec-roadmap CONFIRMED it 2026-10-05
    (obligations.md, harness-receipt-and-doctor-scope); the committed design
    decision 1, goldens, spec scenario and ledger rows 1.2–1.3 stand as ruled.
  • Task 3.5/row 3.2's regression fixture for the OpenCode opsx leftover path
    carries a synthetic name: "OPSX: …" marker: the pinned 1.13.1 OpenCode
    adapter writes only a description field in its leftover command
    frontmatter, so the real leftover never trips doctor's provenance check —
    the fixture proves the path is still walked, not that doctor would flag a
    real one. Raised below for a ruling; not fixed in this PR (out of the ruled
    scope).

Archive

  • cospec archive harness-receipt-and-doctor-scope ran clean as the final
    commit on this branch, no force flags. Moved the change to
    openspec/changes/archive/2026-10-05-harness-receipt-and-doctor-scope/ and
    merged both new requirements ("Init receipt hint follows the selected
    harness", "Doctor checks only the harness files cospec writes") into
    openspec/specs/harness-workflows/spec.md (+2 ~0 -0, all verified).
    git show --stat HEAD lists only openspec/ paths.

Raised for cospec-roadmap (no owner in obligations.md)

  • OpenSpec 1.13.1's OpenCode adapter writes leftover commands with only a
    description field in frontmatter, so doctor's opsx-leftover provenance
    check can never flag a real OpenCode leftover as cospec-authored.
  • The unchanged leftover scan still walks .claude/worktrees/, so
    init --remove-opsx could delete an openspec-written leftover inside a
    nested worktree. This also happens on main today and is outside this PR's
    ruled scope.

🤖 Generated with Claude Code

replygirl and others added 13 commits October 5, 2026 01:55
@replygirl @claude
fix(harness): plan harness-receipt-and-doctor-scope change
c641885 
Proposal, blocking-changes, design, harness-workflows delta, tasks and
verification for the two defects #51 surfaced: the init receipt hint
always spelled for Claude, and doctor's harness checks reading every
.md under a harness dir.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@replygirl @claude
fix(harness): confirm baseline for harness-receipt-and-doctor-scope
f14c589 
Task 1.1: the branch sits on main at 16598da (#51 merged) and
cospec apply exits 0.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@replygirl @claude
test(harness): pin the receipt hint per selected harness
d19e465 
Lifts the receipt's two closing hint lines into receiptHintLines with
today's output, and adds verification 1.6's rows: claude, all and none
keep /cospec:propose; opencode, codex, agents, an explicit
opencode,claude list and a synthetic @ row land as test.failing until
the hint follows the first selected row.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@replygirl @claude
fix(harness): spell the init receipt hint for the selected harness
2120327 
cospec init ended every receipt with /cospec:propose, a command only
Claude Code registers. The two closing hint lines now go through the
first selected row's body dialect and invocation prefix with
transformBody, the respelling its generated bodies get; init and
render.ts read the canon workflow manifest through one shared loader.

Release note: the `cospec init` receipt for `--harness opencode`,
`--harness codex` and `--harness agents` (and for any list or detection
whose first row is one of them) now ends with the corrected hint:
`/cospec-propose` for OpenCode, and
`$cospec-propose (Codex) or /cospec-propose (other agents)` for Codex
and the shared .agents skills. The claude, all, default and none
receipts are unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@replygirl @claude
test(harness): pin doctor's harness checks to files cospec writes
a766c72 
Adds verification 2.1-2.4 and 3.2's rows. A user's .claude/notes.md, a
nested worktree's copy under .claude/worktrees/, a SKILL.md deeper than
one directory, and other markdown under a scan root land as
test.failing until isHarnessDocument narrows. A dangling ref in a
cospec-written command, the legacy .codex/skills root, the table's
command paths, and upstream's legacy opsx command paths in the leftover
scan pass before and after.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@replygirl @claude
fix(harness): check only harness files cospec writes in doctor
e21c226 
isHarnessDocument accepted every .md under a top-level harness dir, so
doctor's stale-harness, mixed-versions and dangling-ref checks read a
user's own .claude/notes.md and a nested worktree's checkout under
.claude/worktrees/. It now accepts exactly <skills-root>/<skill>/SKILL.md
(project and legacy skills roots) and each markdown row's command paths,
matched on the full root. The opsx leftover scan keeps today's breadth:
it moves into init.ts (isLeftoverCandidate, leftoverScanFiles), and
findOpsxFiles and doctor's checkOpsx both read it.

Release note:
- The `cospec init` receipt for `--harness opencode`, `--harness codex`
  and `--harness agents` (and for any list or detection whose first row
  is one of them) ends with the corrected hint lines. The claude, all,
  default and none receipts do not change.
- `cospec doctor` (text and `--json`) no longer reports stale-harness,
  mixed-versions or dangling-ref findings for markdown outside
  <skills-root>/<skill>/SKILL.md and the table's command paths. A repo
  that failed doctor only because of such a file, such as a user's own
  notes or a nested worktree's copy, now passes, and its findings and
  summary counts shrink. Findings on files cospec writes are unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@replygirl @claude
docs(harness): document the receipt hint and doctor's scan boundary
69da39c 
harness-setup.md states that init's Try: hint uses the first selected
harness's spelling and what --harness none prints. The commands.md
doctor row names the files the harness checks read and that user
markdown and nested worktree copies are no longer checked.
docs/harness-integration.md drops its two known-defect passages and
describes the corrected behaviour.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@replygirl @claude
docs(agents): describe the corrected receipt hint and doctor scan
13b5a82 
Replaces shared.md's known-defects sentence with the behaviour this
change ships, then syncs CLAUDE.md and AGENTS.md.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@replygirl @claude
chore(harness): tick the release-note task for the doctor fix
27c283a 
Task 6.1: e21c226's body relays the proposal's BREAKING list (receipt
hint for opencode/codex/agents; doctor's narrowed harness checks) with
no ! and no BREAKING CHANGE footer.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@replygirl @claude
chore(harness): record the full check in the verification ledger
89d11d0 
Task 7.1 and rows 5.1-5.2: mise run check exits 0 and validate --strict
is clean.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@replygirl @claude
chore(harness): record PR #63 and close out the verification ledger
e08950d 
Tasks 1.2, 6.2 and 7.2: the PR number is recorded in proposal.md and the
ledger header; row 4.4 observed the BREAKING list in both fix-commit
bodies and the PR body; validate --strict is clean and every
verification row is [x]. Task 7.3 (archive) stays open for the merge
stage.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@replygirl @claude
chore(harness): tick the archive task row
71661a1 
Task 7.3 (cospec archive) is performed by the next commit.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@replygirl @claude
fix(harness): archive harness-receipt-and-doctor-scope
f644b68 
cospec archive: moved the change to
openspec/changes/archive/2026-10-05-harness-receipt-and-doctor-scope/ and
merged both new requirements (init receipt hint follows the selected
harness; doctor checks only the harness files cospec writes) into
openspec/specs/harness-workflows/spec.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@replygirl
replygirl marked this pull request as ready for review October 5, 2026 08:41
Copilot AI balanced review requested due to automatic review settings October 5, 2026 08:41
Copilot AI reviewed Oct 5, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@replygirl
replygirl merged commit 80ee385 into main Oct 5, 2026
11 of 12 checks passed
@replygirl
replygirl deleted the worktree-harness-receipt-and-doctor-scope branch October 5, 2026 09:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@replygirl