@erclx/canon 5.10.0 → 5.11.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.10.0",
+  "version": "5.11.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/role-orchestrator/SKILL.md

@@ -63,7 +63,7 @@ Report the state of play in the invocation block, and open every later sweep rep
 4. Hand off. Read `${CLAUDE_SKILL_DIR}/references/orchestrator-dispatch.md` and follow it: check the branch is unclaimed, check the row's file set against every track in flight, then dispatch a background worker with `claude --bg`. Fall back to the human-launch line it replaces when the check refuses, the sets overlap, or a stated reason serializes the row behind something already out.
 5. Review the PR. When a worker opens a PR, its first pass runs through `review-pr` in a reviewer dispatched under `role-reviewer` when `### The review dispatch` below fires, and in this session otherwise. Either is the deep, independent pass. The worker's autoship self-review was only the green gate.
    - Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and run the poll under the condition it states rather than checking the board by hand. That runbook holds the routing and the trigger, and a summary of it here is a second source that drifts from it.
-6. Dispatch the handback. A pass posting anything owed, a finding at any severity or a testing question, tells the session holding that branch to run `review-address`, rather than waiting for a person to relay it. Re-review when the worker's own message says the address pass finished, per the channel `role-worker` states, rather than polling for an answer nothing else marks as landed, and send the re-review back to the dispatched reviewer when one took the first pass. Once a pass posts `## Review closed`, and once a UI close names the current head wherever the PR carries a checklist, lift the pull request's draft mark yourself, per Boundaries below. Then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
+6. Dispatch the handback. A pass posting anything owed, a finding at any severity or a testing question, tells the session holding that branch to run `review-address`, rather than waiting for a person to relay it. Re-review when the worker's own message says the address pass finished, per the channel `role-worker` states, rather than polling for an answer nothing else marks as landed, and send the re-review back to the dispatched reviewer when one took the first pass. Once a pass posts `## Review closed`, a UI close names the current head wherever the PR carries a checklist, and `--check` reports `settled`, lift the pull request's draft mark yourself, per Boundaries below. Then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
    - Read `${CLAUDE_SKILL_DIR}/references/orchestrator-handback.md` on reaching this step. It holds how the message is addressed and worded, what to do when no live session holds the branch, and where a worker's reply goes.
 
 A plan written here is written against a tree several branches are already changing, so it names the file set of every track in flight as a constraint, one set per track, read from the Touches column of that track's row. State for each set which of the two acts it forbids, per Constraints in `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. A bare path list leaves the worker guessing, which is how a plan ends up forbidding the repair of a citation the change broke.
@@ -75,7 +75,7 @@ Stamp the block with the commit this session read the tree at, which the same se
 - Run one orchestrator at a time. The board is gitignored, so a second session sees none of this one's writes: two task files land minutes apart under different labels for the same work, one session archives a task mid-sweep in the other, and each archives a plan the other had retargeted. An Owner column does not fix this, since neither session can read the other's rows.
 - Do not implement features in this session. Hand the plan to a worker.
 - Do not merge. Recommend merge or changes. The human merges.
-- Lift a pull request's draft mark once its review closes, whether this session or a reviewer it dispatched closed it, acting directly on the pull request rather than dispatching a worker to do it. Where `canon pr evidence <number> --json` carries a `checklist`, hold it until a UI close names the current head. `role-worker` and `role-reviewer` state the mirroring refusal: neither can verify who is asking or whether review actually closed, so the act stays with this session.
+- Lift a pull request's draft mark once its review closes, whether this session or a reviewer it dispatched closed it, acting directly on the pull request rather than dispatching a worker. Hold it on any `canon pr evidence <number> --check --json` reason but `settled`, reporting that reason, and where that record carries a `checklist`, until a UI close names the current head. `role-worker` and `role-reviewer` state the mirroring refusal: neither can verify who is asking or whether review actually closed, so the act stays with this session.
 - Do not spawn a worker with the Agent tool. An in-process subagent shares this session's context and cannot be steered or reached independently, which breaks the property this boundary protects rather than the mechanism it names. The launch in `orchestrator-launch.md` is a separate `claude --bg` process with its own worktree and its own PR, so it preserves that property instead.
 - Dispatch a background worker only once the collision check in `orchestrator-dispatch.md` clears and the row's file set is disjoint from every track in flight. Colliding with an existing worktree or session is what the check exists to catch rather than a judgment call this session makes case by case. No fixed count binds how many tracks run at once, and Parallelism below states what does.
 - Do not edit tracked files from this session, at any size. The boundary offers no proportionality exception and nothing enforces it.

package/docs/agents/index.md

@@ -35,7 +35,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Migrate](migrate.md): What each canon migrate verb moves and rewrites, what it refuses, the markers that keep an old spelling, and the idempotence check a second run gives
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
-- [The pull request evidence comparison](pr-evidence.md): What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, and why the comparison anchors at the merge base rather than the previous push
+- [The pull request evidence comparison](pr-evidence.md): What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, what the --check read reports as owed, and why the comparison anchors at the merge base rather than the previous push
 - [The pull request local preview](pr-local.md): How canon pr local finds the server a worktree is running, why a server in another worktree is never reported, the refusal reasons it names, and how a close workflow removes the link with --remove
 - [The pull request preview deploy](pr-preview.md): How canon pr preview finds a fenced Cloudflare Pages deploy, dispatches it on a pull request's branch, reads the alias the run prints, the refusal reasons it names, and why an unfenced deploy is refused before anything runs
 - [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading what a review pass covered off its own marker rather than off GitHub's submission stamps, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
@@ -64,4 +64,4 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Teach authoring](teach-authoring.md): Resolving what the next lesson needs before it is written, rendering a lesson body's blocks to HTML, and rewriting the root listing, a contents page, and each lesson's chrome and quiz stepper from its marker regions
 - [Teach](teach.md): Listing learning workspaces with what their records schedule next, opening one with its required files, recording sources and glossary terms, viewing one with its chrome refreshed, where the lesson authoring verbs are described, the refusal reasons, and why every write here runs through a verb
 - [Test order](test-order.md): Reading where an implementation reached history ahead of its test, how a pair is decided, the three verdicts, the coverage the pairing cannot reach, and why the check reports rather than gates
-- [Worktrees](worktrees.md): Reporting which worktrees are reclaimable, removing the ones that are, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
+- [Worktrees](worktrees.md): Reporting which worktrees are reclaimable, removing the ones that are, the hidden verb that clears a stranded bare flag, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes

package/docs/agents/pr-evidence.md

@@ -1,6 +1,6 @@
 ---
 title: The pull request evidence comparison
-description: What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, and why the comparison anchors at the merge base rather than the previous push
+description: What canon pr evidence compares, the marker that lets it edit its own comment rather than duplicate it, the refusal reasons it names, what the --check read reports as owed, and why the comparison anchors at the merge base rather than the previous push
 ---
 
 # The pull request evidence comparison
@@ -58,6 +58,7 @@ image or marks the case new.
 | `no-base`              | GitHub reported no merge base for the pull request.                           |
 | `unreadable-changes`   | GitHub could not list what the pull request changed.                          |
 | `would-empty`          | The render holds no cases and the marked comment holds some. No body.         |
+| `check-writes`         | `--check` was passed with `--preview`, `--local`, or `--checklist`.           |
 
 `no-evidence` is not a refusal a caller reports. A project on a stack that
 carries no evidence path, such as `base` or `python`, hits this reason on
@@ -179,6 +180,52 @@ the checklist land in one comment rather than the checklist going out alone.
 `canon docs pr-local` covers where the address comes from and how the line is
 removed at close.
 
+## What a pull request is still owed
+
+`--check` reads the same changed set and the same thread, renders no body, and
+reports which steps of the ship chain that run after the pull request opens
+never landed on it. It reads the pull request rather than any session's account
+of what it ran, so a session that stopped after opening the pull request leaves
+a branch the check can tell apart from one that needed neither step.
+
+```bash
+canon pr evidence 1341 --check --json
+```
+
+| Reason    | What it means                                                      |
+| --------- | ------------------------------------------------------------------ |
+| `settled` | Nothing is owed. `owed` is empty.                                  |
+| `owed`    | `owed` lists `evidence`, `preview`, or both, always in that order. |
+
+- `evidence` is owed when the changed set carries an evidence image and no
+  comment carries the marker.
+- `preview` is owed when the pull request has a marked comment or an evidence
+  change, a deploy workflow resolves in the checkout the verb runs from, and
+  the marked comment's first line is no `**Preview:**` line. A
+  `**Local preview:**` line does not satisfy it. A project deploying nothing is
+  never owed a preview.
+
+The record carries `owed`, `commentId` when a marked comment exists, and the
+same `preview`, `local`, and `checklist` fields the other reasons carry, so a
+caller reads one shape. It never carries `body`, so a writer branching on `ok`
+and posting `body` cannot act on a check record. Passing `--preview`, `--local`,
+or `--checklist` with it refuses as `check-writes` before any `gh` call, since
+those ask a read to write.
+
+The thread cannot separate a skipped preview step from a failed one. A pull
+request whose deploy run failed or timed out reads as owing a preview, and the
+session that ran it holds the cause. A checklist posted on its own carries no
+marker, so a branch with a checklist and no evidence image never reads as
+owing a preview, though `git-pr` runs the preview step for it. The deploy
+workflow is read from the checkout rather than the pull request's head, so a
+pull request that adds or removes its own deploy workflow reads against trunk's.
+
+An unreadable thread refuses as `gh-failed` rather than reporting `settled` off
+a thread it never read. The check skips the merge base read, which only the
+render needs, so it never refuses `no-base`. The orchestrator's draft lift is
+the caller, and lifts only on `settled`, so a refusal holds it the same as
+`owed` does.
+
 ## What a collapsed comment still leaves to GitHub
 
 GitHub already draws its own before-and-after comparison on the Files Changed

package/docs/agents/worktrees.md

@@ -1,6 +1,6 @@
 ---
 title: Worktrees
-description: Reporting which worktrees are reclaimable, removing the ones that are, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
+description: Reporting which worktrees are reclaimable, removing the ones that are, the hidden verb that clears a stranded bare flag, the record a hook reads back, why the reading keys on the pull request rather than on git ancestry, the refusals it names, and the two removal shapes
 ---
 
 # Worktrees
@@ -24,6 +24,21 @@ Exit codes: `0` every worktree was read, `1` refused. The refusal carries a `rea
 
 An exit code says nothing about a call made from a session, since a shell profile may wrap the binary in a function taking its status from a later command. Read the record's `reason` rather than the exit when a skill consumes this.
 
+## Repair the bare flag
+
+`canon worktrees repair-bare-flag` clears a `core.bare` flag that Claude Code's worktree entry left set in the shared config. It is hidden, so no help listing shows it, because its one caller is a hook rather than a person.
+
+```bash
+canon worktrees repair-bare-flag --root <path> --json
+```
+
+| Option          | Behavior                              |
+| --------------- | ------------------------------------- |
+| `--root <path>` | Repository to repair, default the cwd |
+| `--json`        | Print the record on stdout            |
+
+`--json` writes `{repaired, reason, message}` on stdout, once, whether or not anything was written. `reason` is `flag-unset`, `common-dir-unreadable`, `genuinely-bare`, or `write-failed` when `repaired` is false. `message` carries text when the flag is repaired and when the write failed, and is null on the three quiet skips. A `write-failed` record means the flag is still set, which a lock file or a read-only config causes. A repository whose common dir is not named `.git` keeps its flag. The exit code is always `0`, so a hook never fails a tool call. Without `--json`, a record carrying a message prints it on stderr and any other prints nothing.
+
 ## Reclaim
 
 `canon worktrees reclaim` removes every worktree the reading above called reclaimable, and the branch behind each one.

package/docs/workflow/skill-map.md

@@ -8,7 +8,7 @@ category: Workflow
 
 Groups run in the order a project meets them, so a reader at a known point scans to that group and reads across. The set reconciles the scenarios in [AI workflow](ai-workflow.md) with the lifecycle [target projects](../target/projects.md) describes, rather than inventing a third vocabulary beside those two, so a group name matches neither source exactly and every moment either one names has a group. Each row says when to reach for the skill. What it does is the skill's own description.
 
-This page is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing.
+This page is the corpus the coverage claim is measured against: every name `canon claude skills list --names` reports takes exactly one row here. A skill serving two moments sits at the earlier one, and a mention on any other page is prose rather than routing. The landing page's skills field renders from this page, so its build refuses a skill with no row and a row naming no skill.
 
 ## Set up a project
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.10.0",
+  "version": "5.11.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/commands/gate.ts

@@ -5,7 +5,6 @@ import {
   commandRunner,
   exitCodeFor,
   type GateContext,
-  repairBareFlag,
   type StageResult,
   type Summary,
   runStages,
@@ -24,6 +23,7 @@ import {
   pipeOutput,
   plural,
 } from '@/ui'
+import { repairBareFlag } from '@/worktrees/bare-flag'
 
 interface RunCommandOptions {
   readonly all?: boolean
@@ -97,7 +97,8 @@ async function runGate(opts: RunCommandOptions): Promise<number> {
 
   if (!emitJson && !nested) intro('canon gate run')
 
-  await repairBareFlag(root)
+  const repair = await repairBareFlag(root)
+  if (repair.message !== null) logWarn(repair.message)
 
   const changed = opts.all
     ? { scoped: false, files: [] }

package/src/commands/pr.ts

@@ -32,6 +32,8 @@ import {
   findEvidenceLocal,
   findEvidencePreview,
   groupEvidence,
+  hasMarkedEvidenceComment,
+  readOwed,
   renderEvidenceBody,
 } from '@/pr/evidence'
 import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
@@ -88,6 +90,7 @@ interface EvidenceOptions extends ReadOptions {
   readonly preview?: string
   readonly checklist?: string
   readonly local?: string
+  readonly check?: boolean
 }
 
 interface LocalOptions extends ReadOptions {
@@ -172,6 +175,7 @@ const PULL_REFUSALS: Record<PullRefusal | HeadRefusal, string> = {
  * one `identity.head` owns (`no-object-head`).
  */
 type EvidenceRefusal =
+  | 'check-writes'
   | 'gh-failed'
   | 'no-base'
   | 'unreadable-changes'
@@ -179,6 +183,8 @@ type EvidenceRefusal =
   | 'would-empty'
 
 const EVIDENCE_REFUSALS: Record<EvidenceRefusal, string> = {
+  'check-writes':
+    '--check is a read and renders no body, so it takes none of --preview, --local, or --checklist. Run the check and the render as two calls.',
   'gh-failed':
     'gh could not answer for this repository. Name the pull request number.',
   'unreadable-checklist':
@@ -425,6 +431,10 @@ export function register(program: Command): void {
       '--local <url>',
       "Add this worktree's running server under any preview line, from canon pr local",
     )
+    .option(
+      '--check',
+      'Report which post-pull-request steps the thread is still owed, rendering nothing',
+    )
     .addHelpText(
       'after',
       [
@@ -478,8 +488,19 @@ export function register(program: Command): void {
         'record reports none of the three for it. An unread thread refuses as',
         'gh-failed on both reasons rather than reporting the fields absent.',
         '',
+        '--check reads the same changed set and thread, renders no body, and',
+        'reports what the ship chain still owes the pull request:',
+        '  settled  nothing is owed',
+        '  owed     `owed` lists evidence, preview, or both, in that order',
+        'evidence is owed when an evidence image changed and no comment carries',
+        'the marker. preview is owed when either holds, a deploy workflow in',
+        "this checkout resolves, and the marked comment's first line is no",
+        '**Preview:** line. A failed deploy reads the same as a skipped one.',
+        'The record carries `owed` and the same marked fields. --check refuses',
+        'with --preview, --local, or --checklist as check-writes.',
+        '',
         'Exit codes:',
-        '  0  read, whether it produced a body or reported no-evidence',
+        '  0  read, whether it produced a body, reported no-evidence, or checked',
         '  1  refused, with the reason on stderr or in the JSON record',
         '',
         'Examples:',
@@ -488,6 +509,7 @@ export function register(program: Command): void {
         '  canon pr evidence 1341 --preview https://feat-x.site.pages.dev --json',
         '  canon pr evidence 1341 --checklist .canon/tmp/handoff/ui-checklist/x.md --json',
         '  canon pr evidence 1341 --local http://localhost:5173 --json',
+        '  canon pr evidence 1341 --check --json',
         '',
       ].join('\n'),
     )
@@ -1417,9 +1439,24 @@ async function runEvidence(
 ): Promise<number> {
   const root = resolve(opts.root ?? process.cwd())
   const emitJson = opts.json ?? false
+  const isCheck = opts.check ?? false
 
   intro('canon pr evidence')
 
+  if (
+    isCheck &&
+    (opts.preview !== undefined ||
+      opts.local !== undefined ||
+      opts.checklist !== undefined)
+  ) {
+    return refuseWith(
+      'check-writes',
+      EVIDENCE_REFUSALS['check-writes'],
+      emitJson,
+      root,
+    )
+  }
+
   // Read ahead of anything else, so a bad path refuses before a `gh` round
   // trip rather than after one.
   let suppliedChecklist: string | undefined
@@ -1461,9 +1498,13 @@ async function runEvidence(
     )
   }
 
+  // The check never reads the merge base, so it skips the compare call and
+  // a failed one cannot hold a draft lift for a reason the check never had.
   const [pullFiles, base] = await Promise.all([
     listPullFiles(root, identity.number),
-    readPullMergeBase(root, identity.number, identity.head),
+    isCheck
+      ? undefined
+      : readPullMergeBase(root, identity.number, identity.head),
   ])
   if (pullFiles === undefined) {
     return refuseWith(
@@ -1473,9 +1514,6 @@ async function runEvidence(
       root,
     )
   }
-  if (base === undefined) {
-    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
-  }
 
   const grouped = await groupEvidence(
     [...pullFiles.keys()],
@@ -1533,6 +1571,40 @@ async function runEvidence(
     ...(carriedChecklist !== undefined && { checklist: carriedChecklist }),
   }
 
+  if (isCheck) {
+    const owed = readOwed({
+      hasEvidenceChange: grouped.kind === 'read',
+      hasMarkedComment: hasMarkedEvidenceComment(comments),
+      carriedPreview: carriedPreview !== undefined,
+      deployWorkflowFound:
+        findDeployWorkflow(await readWorkflows(root)).kind === 'found',
+    })
+    logStep(owed.length === 0 ? 'Settled' : 'Owed')
+    logInfo(
+      owed.length === 0
+        ? 'Nothing the ship chain posts after the pull request is missing.'
+        : `missing ${owed.join(', ')}`,
+    )
+    outro()
+    if (emitJson) {
+      process.stdout.write(
+        `${JSON.stringify({
+          root,
+          number: identity.number,
+          reason: owed.length === 0 ? 'settled' : 'owed',
+          owed,
+          ...(commentId !== undefined && { commentId }),
+          ...carried,
+        })}\n`,
+      )
+    }
+    return 0
+  }
+
+  if (base === undefined) {
+    return refuseWith('no-base', EVIDENCE_REFUSALS['no-base'], emitJson, root)
+  }
+
   // A local address rides on a checklist or a hosted preview and never opens
   // a comment alone, so a docs-only branch with a server up posts nothing.
   const hasChecklistAndLocal =

package/src/commands/worktrees.ts

@@ -17,6 +17,7 @@ import {
   type WorktreeVerdict,
 } from '@/worktrees/reclaim'
 import { mainWorktreeRoot } from '@/worktree'
+import { repairBareFlag } from '@/worktrees/bare-flag'
 import {
   removeReclaimable,
   type RemovalOutcome,
@@ -27,6 +28,11 @@ interface ListCommandOptions {
   readonly json?: boolean
 }
 
+interface RepairBareFlagOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
 interface ReclaimCommandOptions {
   readonly dryRun?: boolean
   readonly json?: boolean
@@ -208,6 +214,37 @@ export function register(program: Command): void {
     .action(async (opts: ReclaimCommandOptions) => {
       process.exitCode = await runReclaim(opts)
     })
+
+  worktrees
+    .command('repair-bare-flag', { hidden: true })
+    .description('Clear a core.bare flag that worktree entry left set')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to repair', '.')
+    .option('--json', 'Print the record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Exit codes:',
+        '  0  always, since the caller is a hook that must never fail a tool call',
+        '',
+        'Called by .claude/hooks/bare-flag-repair.sh, the one caller that is not',
+        'a person, so no help listing shows it. A repository whose common dir is',
+        'not named .git keeps its flag, since that is a genuinely bare one.',
+        '',
+        'Examples:',
+        '  canon worktrees repair-bare-flag --root . --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (opts: RepairBareFlagOptions) => {
+      const record = await repairBareFlag(opts.root ?? '.')
+      if (opts.json === true) {
+        process.stdout.write(`${JSON.stringify(record)}\n`)
+      } else if (record.message !== null) {
+        logWarn(record.message)
+      }
+    })
 }
 
 /**

package/src/gate/sequencer.ts

@@ -377,23 +377,3 @@ async function spawn(
     spawnError: code === 'ENOENT' ? `${file} is not on PATH` : undefined,
   }
 }
-
-/**
- * Repairs `core.bare`, which Claude Code's worktree entry leaves set in the
- * shared config and nothing restores.
- *
- * It runs ahead of every stage rather than as one of them, because the flag
- * breaks the git reads that scope the run. The rule itself stays in
- * `scripts/lib/worktree.sh`, which is the one bash function under test, so this
- * calls it rather than restating the guard that spares a genuinely bare
- * repository.
- */
-export async function repairBareFlag(root: string): Promise<void> {
-  await execa('bash', [join(root, 'scripts/core/repair-bare-flag.sh')], {
-    cwd: root,
-    reject: false,
-    stdio: 'inherit',
-    env: { ...gitEnv(), PROJECT_ROOT: root },
-    extendEnv: false,
-  })
-}

package/src/gate/stages.ts

@@ -99,7 +99,6 @@ export const TEST_CORPORA_PATTERNS = [
   '^standards/markdown\\.md$',
   '^tooling/base/reference\\.md$',
   '^tooling/web/configs/scripts/worktree-port\\.sh$',
-  '^scripts/lib/worktree\\.sh$',
   '^scripts/core/check-ignore-parity\\.sh$',
 ]
 

package/src/pr/evidence.ts

@@ -215,6 +215,41 @@ function hasEvidenceMarker(body: string): boolean {
   return (lines[index] ?? '').trim().startsWith(MARKER_PREFIX)
 }
 
+/** Whether any comment carries the evidence marker, url or not. */
+export function hasMarkedEvidenceComment(
+  comments: readonly EvidenceComment[],
+): boolean {
+  return comments.some((comment) => hasEvidenceMarker(comment.body))
+}
+
+/** A post-pull-request step of the ship chain that never landed on the thread. */
+export type OwedStep = 'evidence' | 'preview'
+
+export interface OwedInput {
+  readonly hasEvidenceChange: boolean
+  readonly hasMarkedComment: boolean
+  readonly carriedPreview: boolean
+  readonly deployWorkflowFound: boolean
+}
+
+/**
+ * The steps a pull request is still owed, read off the pull request rather
+ * than off any session's account of what it ran. The thread cannot tell a
+ * skipped preview from one whose deploy failed, so both read as owed.
+ */
+export function readOwed(input: OwedInput): OwedStep[] {
+  const owed: OwedStep[] = []
+  if (input.hasEvidenceChange && !input.hasMarkedComment) owed.push('evidence')
+  if (
+    (input.hasMarkedComment || input.hasEvidenceChange) &&
+    input.deployWorkflowFound &&
+    !input.carriedPreview
+  ) {
+    owed.push('preview')
+  }
+  return owed
+}
+
 /**
  * The REST id of the comment this module already posted, read off its `url`
  * field, since `gh pr view --json comments` reports only a GraphQL id there

package/src/worktrees/bare-flag.ts

@@ -0,0 +1,83 @@
+import { basename } from 'node:path'
+import { execa } from 'execa'
+import { gitEnv } from '@/git-env'
+
+/** Why a run wrote nothing. The three are different states a caller can tell apart. */
+export type BareFlagSkip =
+  | 'flag-unset'
+  | 'common-dir-unreadable'
+  | 'genuinely-bare'
+  | 'write-failed'
+
+/**
+ * What the repair did, or the reason it left the configuration alone.
+ *
+ * `message` is non-null whenever the flag is still set and a caller should say
+ * so, which is a repair and a failed write. The three quiet skips carry none.
+ */
+export type BareFlagRecord =
+  | { readonly repaired: true; readonly reason: null; readonly message: string }
+  | {
+      readonly repaired: false
+      readonly reason: BareFlagSkip
+      readonly message: string | null
+    }
+
+export const REPAIRED_MESSAGE =
+  "Repaired core.bare, which worktree entry left set. Recovery is 'git config core.bare false'."
+
+export const WRITE_FAILED_MESSAGE =
+  "core.bare is set and the repair could not write the config, which a lock file or a read-only config causes. Recovery is 'git config core.bare false'."
+
+const skipped = (reason: BareFlagSkip): BareFlagRecord => ({
+  repaired: false,
+  reason,
+  message: null,
+})
+
+/**
+ * Repairs `core.bare`, which Claude Code's worktree entry leaves set in the
+ * shared config and nothing restores.
+ *
+ * The flag strands the main worktree and breaks the git reads that scope a
+ * verification run, so the gate runs this ahead of every stage. Every git call
+ * drops the repository-resolution variables a git hook exports, so the root
+ * the caller names is the repository that gets read and written.
+ *
+ * A genuinely bare repository keeps its objects at the root and has no `.git`
+ * directory, so its common dir fails the basename test and keeps its flag. That
+ * test is the one case where an unguarded repair does damage.
+ */
+export async function repairBareFlag(root: string): Promise<BareFlagRecord> {
+  const git = (...args: string[]) =>
+    execa('git', ['-C', root, ...args], {
+      env: gitEnv(),
+      extendEnv: false,
+      reject: false,
+    })
+
+  const flag = await git('config', '--get', 'core.bare')
+  if (flag.exitCode !== 0 || flag.stdout.trim() !== 'true') {
+    return skipped('flag-unset')
+  }
+
+  const common = await git(
+    'rev-parse',
+    '--path-format=absolute',
+    '--git-common-dir',
+  )
+  if (common.exitCode !== 0) return skipped('common-dir-unreadable')
+  if (basename(common.stdout.trim()) !== '.git')
+    return skipped('genuinely-bare')
+
+  const write = await git('config', 'core.bare', 'false')
+  if (write.exitCode !== 0) {
+    return {
+      repaired: false,
+      reason: 'write-failed',
+      message: WRITE_FAILED_MESSAGE,
+    }
+  }
+
+  return { repaired: true, reason: null, message: REPAIRED_MESSAGE }
+}

package/scripts/core/repair-bare-flag.sh

@@ -1,19 +0,0 @@
-#!/usr/bin/env bash
-# Repairs `core.bare`, which Claude Code's worktree entry leaves set in the
-# shared config with nothing restoring it. The flag strands the main worktree
-# and breaks the git reads that scope a verification run, so this runs ahead of
-# every stage rather than as one of them.
-#
-# The rule itself lives in `scripts/lib/worktree.sh`, the one bash function in
-# this repository under test, so this file is the invocation and never a second
-# copy of the guard that spares a genuinely bare repository.
-set -e
-set -o pipefail
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-PROJECT_ROOT="${PROJECT_ROOT:-$(cd "$SCRIPT_DIR/../.." && pwd)}"
-
-source "$PROJECT_ROOT/scripts/lib/ui.sh"
-source "$PROJECT_ROOT/scripts/lib/worktree.sh"
-
-repair_bare_flag "$PROJECT_ROOT"

package/scripts/lib/worktree.sh

@@ -1,20 +0,0 @@
-#!/usr/bin/env bash
-
-# Claude Code's worktree entry writes core.bare into the parent repository's
-# shared config and its exit never restores it, stranding every later command in
-# the main worktree. Sourced by verify.sh, which runs the repair before any stage
-# because the flag breaks the git reads that scope the run.
-
-repair_bare_flag() {
-  local root="${1:-$PROJECT_ROOT}"
-  local common_dir
-  [ "$(git -C "$root" config --get core.bare 2>/dev/null || echo false)" = true ] || return 0
-
-  common_dir=$(git -C "$root" rev-parse --path-format=absolute --git-common-dir 2>/dev/null) || return 0
-  # A genuinely bare repository keeps its objects at the root and has no .git
-  # directory, so it fails this test and keeps its flag.
-  [ "$(basename "$common_dir")" = ".git" ] || return 0
-
-  git -C "$root" config core.bare false
-  log_warn "Repaired core.bare, which worktree entry left set. Recovery is 'git config core.bare false'."
-}