buddy-agent-harness 1.1.0 → 1.2.0

package/src/diagnose-bridges/doctor-guidance.ts

@@ -72,6 +72,12 @@ export type GlobalInstructionProblem =
 	| 'global-instructions-overridden'
 	| 'global-instructions-emptied'
 
+/**
+ * What a repository lacks for the git worktrees Claude Code creates under `.claude/worktrees/`;
+ * each is an offer `init` and `enhance` make, never a fault in a file the owner wrote.
+ */
+export type WorktreeProblem = 'worktrees-untracked' | 'worktrees-scanned' | 'worktree-base-unset'
+
 /** Everything `doctor` can report against, across every section. */
 export type DoctorProblem =
 	| BridgeProblem
@@ -80,6 +86,7 @@ export type DoctorProblem =
 	| ConfigurationFault
 	| McpProblem
 	| NonstandardProblem
+	| WorktreeProblem
 
 /** Alias kept for callers that name the whole set rather than one section. */
 export type ConfigurationProblem = DoctorProblem
@@ -192,6 +199,7 @@ export const pnpmSkillRef = (invocation: string): string =>
 	`\`${invocation}\` (pnpm install: \`pnpm-${commandInvocation}-${invocation.slice(invocation.indexOf(':') + 1)}\`)`
 
 export const initSkillRef: string = pnpmSkillRef(initSkillInvocation)
+export const enhanceSkillRef: string = pnpmSkillRef('/buddy-agent-harness:enhance')
 export const repairSkillRef: string = pnpmSkillRef(repairSkillInvocation)
 
 /** Where the user authors the golden MCP server set, named in every MCP repair that points at it. */
@@ -589,6 +597,38 @@ const nonstandardTable: Record<NonstandardProblem, RepairRow> = {
 
 export const nonstandardRepairs: readonly Repair[] = repairsOf(nonstandardTable)
 
+/** Who offers every worktree repair, named the same way in each row. */
+const worktreeOffer = `${initSkillRef} offers it, or ${enhanceSkillRef} where the repository already has an AGENTS.md`
+
+const worktreeTable: Record<WorktreeProblem, RepairRow> = {
+	'worktrees-untracked': {
+		detail:
+			'.claude/worktrees/ is not git-ignored, so every agent worktree Claude Code creates there shows up as untracked in git status',
+		repair: ({ file }) => ({ command: '', instruction: `add \`.claude/worktrees/\` to ${file} — ${worktreeOffer}` }),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which offers the .gitignore line`,
+	},
+	'worktrees-scanned': {
+		detail:
+			'this config does not exclude .claude/worktrees, so the tool walks into each agent worktree, a whole checkout with its own config, and Biome stops on the nested root configuration',
+		repair: ({ file }) => ({
+			command: '',
+			instruction: `add \`"!**/.claude/worktrees"\` to \`files.includes\` in ${file} — ${worktreeOffer}`,
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which offers the exclusion`,
+	},
+	'worktree-base-unset': {
+		detail:
+			'worktree.baseRef is unset, so agent worktrees branch from the default branch rather than the current HEAD — work on a feature branch starts without its commits',
+		repair: ({ file }) => ({
+			command: '',
+			instruction: `decide whether agent worktrees should branch from HEAD, and if so set \`"worktree": { "baseRef": "head" }\` in ${file} — ${worktreeOffer}`,
+		}),
+		skillRepair: () => `run ${initSkillRef} or ${enhanceSkillRef}, which explains the trade-off and offers the setting`,
+	},
+}
+
+export const worktreeRepairs: readonly Repair[] = repairsOf(worktreeTable)
+
 /**
  * Annotated over the whole union rather than inferred, so an added problem fails to compile until
  * its section carries it.
@@ -600,6 +640,7 @@ const doctorTable: Record<DoctorProblem, RepairRow> = {
 	...configurationTable,
 	...mcpTable,
 	...nonstandardTable,
+	...worktreeTable,
 }
 
 export const doctorRepairs: readonly Repair[] = repairsOf(doctorTable)
@@ -612,7 +653,7 @@ export function repairFor(problem: DoctorProblem): Repair {
 export const doctorSkill = {
 	name: 'doctor-buddy-agent-harness',
 	description:
-		'Use this skill when a repository loads no project skills, when skills are missing after a clone, when a harness appears to be ignoring AGENTS.md, or when checking whether the agent configuration bridges into .claude/skills and the other harness files still resolve.',
+		"Checks whether a repository's agent configuration bridges into .claude/skills and the other harness files still resolve — when a repository loads no project skills, when skills are missing after a clone, or when a harness appears to be ignoring AGENTS.md.",
 } as const
 
 /** Written into the generated skill so a reader knows not to edit it in place. */
@@ -699,6 +740,7 @@ Every \`problem\` name routes to exactly one page. Load the page for the finding
 | \`references/configuration.md\` | a finding about the configuration around the bridges rather than a bridge |
 | \`references/mcp.md\` | any finding whose path is an MCP locator — **always** before acting on a credential finding |
 | \`references/nonstandard.md\` | a finding about configuration only one harness can read |
+| \`references/worktrees.md\` | a finding about the agent worktrees Claude Code creates under \`.claude/worktrees/\` |
 | \`references/harnesses/<name>.md\` | the paths and files one named harness uses |
 
 ## Rules
@@ -709,6 +751,12 @@ Every \`problem\` name routes to exactly one page. Load the page for the finding
 - Never repeat a value from a file an \`mcp-literal-secret\` or \`mcp-committed-secret\` finding points at. The report withheld it on purpose, and quoting it back puts it in the transcript anyway.
 - Never write outside the repository. A \`globalInstructions\` repair is a step for the user to take in their own home directory; hand it over exactly as reported.
 - Write instructions in \`AGENTS.md\`, never in \`CLAUDE.md\`. Content written there reaches one harness, drifts from the canonical file, and — because Claude Code prefers it — takes \`AGENTS.md\` out of that harness's context entirely.
+
+## Done when
+
+- **C1.** The reply names each problem the report found and its cause, or, when the report found none, says the configuration is healthy and calls for no change.
+- **C2.** No bridge, skill, or instruction file changed: no \`init\` ran, and nothing was written to \`CLAUDE.md\`.
+- **C3.** The reply repeats no value that a secret finding withheld.
 `
 }
 
@@ -988,6 +1036,23 @@ ${repairTable(nonstandardRepairs)}
 A harness directory that is a **symlink** is a projection someone already made, not configuration authored here. An artifact is reported whether or not its harness is enabled: a \`.cursorrules\` in a repository nobody opens in Cursor is still instruction content \`AGENTS.md\` does not carry, and filtering by the enabled set would hide exactly the drift worth converting.
 
 Hooks, LSP settings, and output styles are not covered yet. Their event names and shapes differ by harness with no safe projection, and half-reporting them would be worse than the silence.
+`,
+		},
+		{
+			path: 'references/worktrees.md',
+			content: `${generatedSkillWarning}
+
+# Agent worktree findings
+
+Claude Code runs a session started with \`--worktree\`, and a subagent isolated in a worktree, in a git worktree under \`.claude/worktrees/<name>/\` inside the repository. That place is by design, and no setting moves it. These findings are what a repository needs so the worktrees there do no harm. \`doctor\` checks them only where a \`.claude\` directory exists.
+
+${repairTable(worktreeRepairs)}
+
+None of these is a fault in a file the owner wrote, and none is a \`repair\` correction. Each is an offer the \`init-buddy-agent-harness\` and \`enhance\` skills make, one at a time, and write only on approval.
+
+\`worktree-base-unset\` is a choice, not an error. The default branch suits agents given unrelated tasks; \`"head"\` suits agents asked to build on the branch in front of them. Put the trade-off to the owner, and report an explicit \`"fresh"\` as their answer rather than as a finding — \`doctor\` already does.
+
+\`worktrees-scanned\` is checked for Biome only, the one tool with a confirmed failure. A repository whose ESLint, Prettier, knip, or TypeScript configuration walks the tree can hit the same thing; the skills look for those when they make the offer.
 `,
 		},
 		...harnessRegistry.map((harness) => harnessPage(harness, initReferences.has(harness.name))),

package/src/diagnose-bridges/doctor.command.ts

@@ -7,6 +7,7 @@ import { collapseHome, displayBinPath, fail, parseHarnessOption } from '../comma
 import { type ConfigurationFinding, diagnoseConfiguration } from '../diagnose-configuration/diagnose-configuration.ts'
 import { diagnoseMcp } from '../diagnose-mcp/diagnose-mcp.ts'
 import { diagnoseNonstandard } from '../diagnose-nonstandard/diagnose-nonstandard.ts'
+import { diagnoseWorktrees } from '../diagnose-worktrees/diagnose-worktrees.ts'
 import { referenceLayers } from '../references/references.ts'
 import { type DiagnoseResult, diagnoseBridges } from './diagnose-bridges.ts'
 import { commandInvocation, type DoctorProblem, type RepairAction } from './doctor-guidance.ts'
@@ -116,6 +117,7 @@ export async function diagnoseReport(args: {
 			...diagnoseConfiguration({ root, git, cli: commandInvocation }),
 			...diagnoseMcp({ root, git, cli: commandInvocation }),
 			...diagnoseNonstandard({ root, cli: commandInvocation }),
+			...diagnoseWorktrees({ root, git, cli: commandInvocation }),
 		]
 		const { layers: rows } = listReferences(
 			await referenceLayers({

package/src/diagnose-bridges/git-bridge-state.ts

@@ -37,6 +37,11 @@ export class GitBridgeState {
 		this.repoRootPrefix = git(root, ['rev-parse', '--show-prefix'])?.trim()
 	}
 
+	/** Whether `root` is inside a git work tree at all; a check that needs git's answer skips when not. */
+	isRepository(): boolean {
+		return this.repoRootPrefix !== undefined
+	}
+
 	/** The skip-worktree bit is a hint some checkouts clear, so it is verified rather than assumed. */
 	trackingOf(path: string): TrackingState {
 		if (this.repoRootPrefix === undefined) return 'untracked'

package/src/diagnose-worktrees/diagnose-worktrees.ts

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { type RepairAction, repairFor, type WorktreeProblem } from '../diagnose-bridges/doctor-guidance.ts'
+import type { GitBridgeState } from '../diagnose-bridges/git-bridge-state.ts'
+import { isRecord } from '../is-record/is-record.ts'
+
+/**
+ * The agent-worktree half of `doctor`: what a repository lacks for the git worktrees Claude Code
+ * creates inside it under `.claude/worktrees/`. Read-only.
+ */
+export type WorktreeFinding = {
+	/** Repository-relative path the finding is about. */
+	path: string
+	problem: WorktreeProblem
+	detail: string
+	/** Always an empty `command`: each repair is an offer the owner approves. */
+	repair: RepairAction
+}
+
+export type DiagnoseWorktreesOptions = {
+	root: string
+	git: GitBridgeState
+	/** How to name this tool in the repair commands. */
+	cli: string
+}
+
+/** The trailing slash matters: `git check-ignore` matches a directory rule only against a directory path. */
+export const worktreeDirectory = '.claude/worktrees/'
+
+const biomeConfigs = ['biome.json', 'biome.jsonc']
+const claudeSettings = '.claude/settings.json'
+
+/** `undefined` when the file is missing or does not parse; either way Claude Code reads no base from it. */
+function readJson(path: string): unknown {
+	try {
+		return JSON.parse(readFileSync(path, 'utf8'))
+	} catch {
+		return undefined
+	}
+}
+
+/**
+ * Checked only where `.claude/` exists, the sign the repository is worked in with Claude Code.
+ * Biome is the one tool checked: it is the confirmed failure, and the others are offered by the
+ * skills without a finding.
+ */
+export function diagnoseWorktrees({ root, git, cli }: DiagnoseWorktreesOptions): WorktreeFinding[] {
+	if (!existsSync(join(root, '.claude'))) return []
+
+	const findings: WorktreeFinding[] = []
+	const add = (path: string, problem: WorktreeProblem) => {
+		const { detail, repair } = repairFor(problem)
+		findings.push({ path, problem, detail, repair: repair({ file: path }, cli) })
+	}
+
+	if (git.isRepository() && !git.isIgnored(worktreeDirectory)) add('.gitignore', 'worktrees-untracked')
+
+	for (const config of biomeConfigs) {
+		const path = join(root, config)
+		if (existsSync(path) && !readFileSync(path, 'utf8').includes('.claude/worktrees')) add(config, 'worktrees-scanned')
+	}
+
+	const settings = readJson(join(root, claudeSettings))
+	const worktree = isRecord(settings) ? settings['worktree'] : undefined
+	// An explicit `"fresh"` is the owner's choice; only an unset key is reported.
+	if (!isRecord(worktree) || worktree['baseRef'] === undefined) add(claudeSettings, 'worktree-base-unset')
+
+	return findings
+}

package/src/index.ts

@@ -56,6 +56,7 @@ export type {
 	InstructionProblem,
 	McpProblem,
 	Repair,
+	WorktreeProblem,
 } from './diagnose-bridges/doctor-guidance.ts'
 export {
 	bridgeRepairs,