repo-harness 0.25.3 → 0.25.4

package/README.md

@@ -119,11 +119,14 @@ helpers do not rediscover tools from a caller's `PATH`; rerun
 `repo-harness update` after relocating or replacing Git for Windows.
 
 The global bootstrap: installs the npm package as the global CLI, refreshes
-repo-harness skill aliases, installs user-level hook adapters, and records an
-explicit install profile. It is idempotent and does not apply repo-local workflow
-files to the current directory. `--dry-run --json` lists components to install,
-skip, and remove first. Profiles, native Codex delegation authority, refresh commands, and the
-read-only `setup check` audit:
+repo-harness skill aliases, installs user-level hook adapters, and records the
+plugin selection. With no flag it installs core and every plugin that the host
+can run; `--plugins <ids>` selects exactly those plugins, and `--no-plugins`
+installs core only. It is idempotent and does not apply repo-local workflow
+files to the current directory. `--dry-run --json` lists the plugins to install,
+keep, remove and skip first. Plugins, the protocol 2 to 3 migration, native
+Codex delegation authority, refresh commands, and the read-only `setup check`
+audit:
 [`install-profiles.md`](docs/reference-configs/install-profiles.md).
 
 ### 3. Preview the repo-local contract
@@ -245,7 +248,7 @@ task queue.
 | --- | --- | --- |
 | Issue and PR | Scope, ownership, dependencies, status and review evidence | The assigned GitHub issue |
 | Session support | Repository context, hooks and handoffs | `repo-harness init` |
-| Existing observations | Read retained task and runtime records | `repo-harness fleet board --json` |
+| Board | Read the sub-issues, pull requests, plan block and seat terminals of one parent issue | `repo-harness board --parent <n> --json` |
 
 New work uses a bounded issue brief and the current repository rules. Historical
 Sprint, binding and Lease records remain readable for operator and closeout
@@ -323,15 +326,15 @@ Keep the issue, branch, verification result and next action in the handoff.
 Re-read the issue and PR before continuing. Use the approved OAR and Herdr host
 paths for an assigned agent. repo-harness has no PM or Engineer scheduling API.
 
-### Existing task observations
+### Board of a parent issue
 
 ```bash
-repo-harness fleet board --json
+repo-harness board --parent <n> --json
 ```
 
-The board reads retained task, Lease, publication, inbox and runtime evidence.
-It does not claim work or create an Engineer binding. Completion and cleanup
-helpers remain for existing records.
+The board reads the sub-issues, pull requests, plan block and hc seat terminals
+of one parent issue. It does not claim work or create an Engineer binding.
+Completion and cleanup helpers remain for existing records.
 
 Use [repo-harness](SKILL.md) for scope and worker ownership,
 [repo-harness-product](assets/skills/repo-harness-product/SKILL.md) for requested
@@ -351,20 +354,6 @@ violations. repo-harness shows each suggestion with its metrics, bounded evidenc
 and module statistics, and records the user decision. It never executes a refactor; an
 accepted suggestion goes through the normal plan and pull request workflow.
 
-### External source intake
-
-```bash
-repo-harness external-source refresh   # one bounded, explicitly enabled GitHub observation
-repo-harness external-source bind --repo <id> --source-revision <digest> --session <selector.json>
-repo-harness external-source bindings  # binding edges and current drift attention
-```
-
-Intake is inert by design. An observed Issue mints no execution authority and
-does not become a runnable task on its own; binding attaches an immutable source
-revision to an existing admitted session selected by its provider issue, immutable
-claim, approved grant and session binding digest. The selector comes from task
-session discovery. Binding never creates a claim or approval.
-
 ### Persistent acceptance review
 
 Before review, configure the repository's manual `external_sources` policy and
@@ -613,8 +602,8 @@ repo-harness commit scripts or hooks unless that repo adopts the same policy.
 
 ## Current Release
 
-- npm package: `repo-harness@0.25.3`
-- Generated workflow stamp: `repo-harness@0.25.3+template@0.25.3`
+- npm package: `repo-harness@0.25.4`
+- Generated workflow stamp: `repo-harness@0.25.4+template@0.25.4`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release notes and history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/agents/fleet/gatekeeper.md

@@ -9,7 +9,7 @@ effort: high
 Review only a medium or high tier diff under Review by risk in the development flow; a low tier gets no review.
 When `agents/fleet/known-gaps.md` is present, read the row for the PR's producer and run its named checks in addition to the tier's review. The table rules govern how the row combines with the review.
 Read the current diff only. A defect in untouched code is a non-blocking note, not a finding.
-From the second round, read only the hunks that changed after the previous round.
+Take the scope of each round from the round rules in `repo-harness-issue-flow`, `references/acceptor.md` §2.2.
 Keep review read-only. The Bot owns fixes and publication.
 Return `VERDICT: PASS`, `VERDICT: FAIL`, or `VERDICT: BLOCKED` first.
 Record branch, HEAD, dirty scope and the assigned goal. Preserve unrelated work.

package/assets/operator/{fleet-windows-job-controller.ps1 → windows-job-controller.ps1}

@@ -6,7 +6,7 @@ using System.Diagnostics;
 using System.Runtime.InteropServices;
 using System.Text;
 
-public static class RepoHarnessFleetJob {
+public static class RepoHarnessOperatorJob {
   [StructLayout(LayoutKind.Sequential)]
   public struct BasicLimitInformation {
     public long PerProcessUserTimeLimit;
@@ -137,9 +137,9 @@ public static class RepoHarnessFleetJob {
 }
 '@
 
-$job = [RepoHarnessFleetJob]::CreateJobObject([IntPtr]::Zero, $null)
+$job = [RepoHarnessOperatorJob]::CreateJobObject([IntPtr]::Zero, $null)
 if ($job -eq [IntPtr]::Zero) { throw 'CreateJobObject failed' }
-[RepoHarnessFleetJob]::ConfigureKillOnClose($job)
+[RepoHarnessOperatorJob]::ConfigureKillOnClose($job)
 
 function Write-Response([string]$type) {
   [Console]::Out.WriteLine((@{ type = $type } | ConvertTo-Json -Compress))
@@ -149,26 +149,26 @@ function Write-Response([string]$type) {
 function Wait-ForZeroActiveProcesses([IntPtr]$handle) {
   $deadline = [DateTime]::UtcNow.AddSeconds(5)
   while ([DateTime]::UtcNow -lt $deadline) {
-    if ([RepoHarnessFleetJob]::ActiveProcesses($handle) -eq 0) { return $true }
+    if ([RepoHarnessOperatorJob]::ActiveProcesses($handle) -eq 0) { return $true }
     Start-Sleep -Milliseconds 10
   }
-  return ([RepoHarnessFleetJob]::ActiveProcesses($handle) -eq 0)
+  return ([RepoHarnessOperatorJob]::ActiveProcesses($handle) -eq 0)
 }
 
 function Close-CleanJob([IntPtr]$handle, [bool]$terminate) {
-  if ($terminate -and -not [RepoHarnessFleetJob]::TerminateJobObject($handle, 1)) {
+  if ($terminate -and -not [RepoHarnessOperatorJob]::TerminateJobObject($handle, 1)) {
     throw 'TerminateJobObject failed'
   }
   if (-not (Wait-ForZeroActiveProcesses $handle)) { return $false }
-  if (-not [RepoHarnessFleetJob]::CloseHandle($handle)) { throw 'CloseHandle failed' }
+  if (-not [RepoHarnessOperatorJob]::CloseHandle($handle)) { throw 'CloseHandle failed' }
   return $true
 }
 
 function Close-FailedJob([IntPtr]$handle) {
   if ($handle -eq [IntPtr]::Zero) { return }
-  try { [void][RepoHarnessFleetJob]::TerminateJobObject($handle, 1) } catch { }
+  try { [void][RepoHarnessOperatorJob]::TerminateJobObject($handle, 1) } catch { }
   try { [void](Wait-ForZeroActiveProcesses $handle) } catch { }
-  try { [void][RepoHarnessFleetJob]::CloseHandle($handle) } catch { }
+  try { [void][RepoHarnessOperatorJob]::CloseHandle($handle) } catch { }
 }
 
 function Stop-ExactCollector([System.Diagnostics.Process]$process) {
@@ -207,7 +207,7 @@ try {
       }
       $startInfo = New-Object System.Diagnostics.ProcessStartInfo
       $startInfo.FileName = [string]$request.executable
-      $startInfo.Arguments = [RepoHarnessFleetJob]::QuoteArgument([string]$request.collector_path)
+      $startInfo.Arguments = [RepoHarnessOperatorJob]::QuoteArgument([string]$request.collector_path)
       $startInfo.UseShellExecute = $false
       $startInfo.RedirectStandardInput = $true
       $startInfo.RedirectStandardOutput = $true
@@ -228,12 +228,12 @@ try {
       }
       # This is the exact kernel handle returned for the child this controller
       # created. No PID is ever accepted or reopened across this boundary.
-      if (-not [RepoHarnessFleetJob]::AssignProcessToJobObject($job, $collector.Handle)) {
+      if (-not [RepoHarnessOperatorJob]::AssignProcessToJobObject($job, $collector.Handle)) {
         if (-not (Stop-ExactCollector $collector)) { throw 'collector assignment failed and exact collector did not exit' }
         Write-Response 'cleanup_failed'
         break
       }
-      [RepoHarnessFleetJob]::BeginForwarding($collector)
+      [RepoHarnessOperatorJob]::BeginForwarding($collector)
       $assigned = $true
       Write-Response 'assigned'
       continue

package/assets/reference-configs/agentic-development-flow.md

@@ -16,10 +16,10 @@
 ## CI cost
 Size PR CI by the diff, the same as step 4. A full suite on each small PR spends runner time and adds no evidence that the affected tests and the daily run do not already give. The repo-harness source repository uses this shape in `.github/workflows/ci.yml`.
 
-- Triggers: run PR checks on `pull_request`. Do not also trigger `push` on feature branches; that runs each commit twice. A `push` to the default branch runs the affected selection for the merged diff, not the full suite.
+- Triggers: run PR checks on `pull_request`. Do not also trigger `push` on feature branches; that runs each commit twice. A `push` to the default branch runs only the selection job in report mode, with no tests.
 - Superseded runs: set `concurrency` to one group per PR number with `cancel-in-progress: true` for `pull_request` events only. Do not cancel scheduled runs.
 - Selection: a first job reads the diff against the PR base and outputs a mode. Later jobs read the mode in a job-level `if:`.
-  - A docs-only diff (`docs/**/*.md`, README, CHANGELOG) skips build and test jobs when no test or script reads the changed files. Keep link and format checks. A document that is program input, such as a projected copy, a parsed contract or a generated region, runs its consumer tests.
+  - A docs-only diff runs only the tests that name a changed document, including a deleted one. With no such test, it skips build and test jobs, and the required aggregate check still reports. One function names the documentation paths; in the repo-harness source repository it is `isDocumentationPath` in `scripts/select-ci-coverage.ts`. Keep link, format and advisory document checks. A document that is program input, such as a projected copy, a parsed contract or a generated region, is outside the documentation rule or has a test that names it, so a change to it runs its consumer tests.
   - A code diff runs typecheck plus the tests that the diff affects. Use the runner's change detection (`vitest --changed`, `jest --changedSince`, `nx affected`, `turbo run --filter=...[<base>]`, `pytest --testmon`) or an import-graph selector.
   - A change to a shared input (lockfile, root build or test config, CI workflow, a test helper with no mapped consumer) runs the full suite on that PR. A selector that cannot map a changed file widens the run; it never shrinks it.
 - Required checks: skip a job with a job-level `if:`, not with workflow-level `paths` or `paths-ignore`. GitHub counts a skipped job as passing for a required check. A workflow that never starts leaves its required check pending and blocks the merge.
@@ -108,10 +108,14 @@ that PM restriction. OAR owns coding-agent execution. herdr-core (`hc`) owns
 terminals, and Herdr.app owns panes and visibility. A new Bot host adapts to that path; it does not add a new coding
 runtime or task authority.
 
-The `orchestrator` fleet role is the long-lived coordinator and integrator seat
-of `repo-harness-issue-flow`. Start it with `claude --agent orchestrator`. The
-fleet projects it to Claude only. It dispatches work and follows PRs and CI. It
-edits no product code and dispatches no subagents.
+The orchestrator seat is the long-lived coordinator and integrator seat of
+`repo-harness-issue-flow`. Start it with the argv that
+`repo-harness seats argv orchestrator` prints. It dispatches work and follows
+PRs and CI. It edits no product code. It may call the read-only roles
+`gatekeeper`, `explorer` and `deep-reasoner` as sub-agents. The writers
+(`fast-worker`, `deep-worker`, `root-cause-prover`) and the Codex
+cross-review never run as its sub-agents: they run in Herdr seats, for
+worktree isolation and one writer per file.
 
 The bot selects scope, worker and verification by risk. Use independent gatekeeper/cross-model review for large changes, security/permissions or model uncertainty; do not rerun a passing check or require multiple re-gates.
 
@@ -119,13 +123,19 @@ The bot selects scope, worker and verification by risk. Use independent gatekeep
 
 A hazard is a change that runs or exposes code, secrets, data or network access on a machine or in CI. One hit on any item sets an internal PR to High under [Review by risk](#review-by-risk). An external PR stops and escalates under its protocol; that behavior does not change.
 
-- Changes a workflow or other CI configuration under `.github/`.
-- Changes a release, publish, update or install script, or a package script that runs at install or release.
-- Changes a `Dockerfile` or another container build file.
-- Adds a network address, endpoint or telemetry.
-- Reads credentials, such as tokens, keys, `~/.ssh`, `~/.npmrc` or credential environment variables.
-- Adds or changes a dependency or a lockfile entry. A lockfile-only bump is still a hit; its source does not lower the tier.
-- Adds a binary, or an encoded or opaque blob, such as base64, long hex, minified or otherwise unreadable content.
+<!-- review-hazards:list:begin -->
+The board rule R3 reads only the rows with `path_visible: true`: a changed path that matches one of their patterns is a hit. Reviewers apply every row.
+
+| Hazard | Paths that R3 reads |
+| --- | --- |
+| Changes a workflow or other CI configuration under `.github/`. | `.github/**` |
+| Changes a release, publish, update or install script, or a package script that runs at install or release. | None (`path_visible: false`) |
+| Changes a `Dockerfile` or another container build file. | `**/Dockerfile`, `**/Dockerfile.*`, `**/*.Dockerfile`, `**/Containerfile`, `**/Containerfile.*` |
+| Adds a network address, endpoint or telemetry. | None (`path_visible: false`) |
+| Reads credentials, such as tokens, keys, `~/.ssh`, `~/.npmrc` or credential environment variables. | None (`path_visible: false`) |
+| Adds or changes a dependency or a lockfile entry. A lockfile-only bump is still a hit; its source does not lower the tier. | `**/bun.lock`, `**/bun.lockb`, `**/package-lock.json`, `**/npm-shrinkwrap.json`, `**/yarn.lock`, `**/pnpm-lock.yaml`, `**/Cargo.lock`, `**/go.sum`, `**/poetry.lock`, `**/uv.lock`, `**/Pipfile.lock`, `**/Gemfile.lock`, `**/composer.lock` |
+| Adds a binary, or an encoded or opaque blob, such as base64, long hex, minified or otherwise unreadable content. | None (`path_visible: false`) |
+<!-- review-hazards:list:end -->
 
 ### Review by risk
 The diff sets the tier. The author does not: a human change and a model change with the same diff get the same tier. One hit on a higher signal sets the higher tier.
@@ -136,7 +146,7 @@ The diff sets the tier. The author does not: a human change and a model change w
 | Medium | Cross-module behavior changes; public API changes; more than 10 non-generated implementation files; shared runtime changes; authentication-adjacent changes; or unresolved behavior uncertainty. |
 | High | Any hit on the [change hazard list](#change-hazards); permissions or sandbox grants; hooks and the mutation guard; deletion paths; `deploy/sql/`; code that writes to GitHub; or a change across more than one capability boundary in `.archcontext/model/`. |
 
-Review follows the `repo-harness-issue-flow` skill, [references/acceptor.md](../../assets/skills/repo-harness-issue-flow/references/acceptor.md). The tier selects the depth: no independent review for Low, one fresh-context review for Medium, and the gatekeeper plus one cross-model review for High, one round each. The Acceptor SOP owns the round, findings and publish steps.
+Review follows the `repo-harness-issue-flow` skill, [references/acceptor.md](../../assets/skills/repo-harness-issue-flow/references/acceptor.md). The tier selects the depth: no independent review for Low, one fresh-context review for Medium, and the gatekeeper plus one review, preferably cross-model, for High. The round rules (who reviews each round, the claims of a round, the round-2 scope and the convergence rule) are only in [references/acceptor.md §2.2](../../assets/skills/repo-harness-issue-flow/references/acceptor.md#22-rounds). The Acceptor SOP owns the round, findings and publish steps.
 
 Low accept-seat skip: a Low PR whose `Required / CI` is SUCCESS on the PR head and whose PR body holds the author verification evidence (the commands and their outcomes) takes no accept seat and no acceptance record. Do not dispatch a Codex, Herdr or OAR accept seat for it. `Required / CI` and that evidence are the proof surface. A Low PR that lacks either condition is not eligible to merge until both hold. Medium and High keep the full Acceptor SOP.
 
@@ -144,19 +154,19 @@ Worked example (docs-only Low path): the PR edits `docs/bot-onboarding.md` only.
 
 Rules for every tier:
 - The reviewer reads the current diff only. A defect in code the diff did not touch is a non-blocking note; open an issue for it, do not add a finding.
-- From the second round, the reviewer reads only the hunks that changed after the previous round. The three-round limit stays.
+- Review rounds follow [references/acceptor.md §2.2](../../assets/skills/repo-harness-issue-flow/references/acceptor.md#22-rounds). The reviewer reads CI on the exact head and the recorded evidence, and does not rerun a passing check ([references/acceptor.md §2.1](../../assets/skills/repo-harness-issue-flow/references/acceptor.md#21-evidence)).
 - When an independent review ran, the PR description lists each finding with its disposition: fixed, or closed with the reason.
 - A low tier adds no review. A new test file or a rebase does not raise the tier.
 - Changing implementation and test assertions together does not raise the tier. Within the tier's existing review, check whether assertions preserve the intended behavior and whether removed or weakened coverage has a valid requirement-based reason. At Low, the author performs this check in self-review. Record the reason for each assertion change in the PR; never change assertions only to make a test pass. Do not dispatch a separate test-review gate.
 - A parent, coordinator or merge session reuses recorded acceptance when the reviewed diff, relevant base context, verification inputs and environment still match, and the review meets the current tier. The PR records the reviewed revision or diff, commands, results and finding dispositions. A change of session or reviewer is not a reason to repeat acceptance.
 - A batch integration PR (`repo-harness-issue-flow`, [references/orchestrator.md](../../assets/skills/repo-harness-issue-flow/references/orchestrator.md) §9.3) reuses the acceptance record of each member when every member merged without conflict and the batch adds no commit of its own. It needs no new review round. A Low member has no acceptance record to reuse. Required checks on the batch head still apply.
-- After a change, verify the affected behavior and review the changed hunks with their affected context. Retain valid evidence for unchanged scope; add only missing tier coverage. A rebase alone does not require a new full review, but changed base behavior or conflict resolution can invalidate affected evidence. Reuse never substitutes for required checks on the current head or the current-main merge requirement.
+- After a change, verify the affected behavior. The review scope of each round after a change is in [references/acceptor.md §2.2](../../assets/skills/repo-harness-issue-flow/references/acceptor.md#22-rounds). Retain valid evidence for unchanged scope; add only missing tier coverage. A rebase alone does not require a new full review, but changed base behavior or conflict resolution can invalidate affected evidence. Reuse never substitutes for required checks on the current head or the current-main merge requirement.
 - A downstream repository maps its own release surfaces, for example public API, wire format, DDL/SQL and permissions, to the High tier.
 
 The bot measures progress by side effects only: commits, pushes, evidence events and PR or check changes. It does not resume a worker to check liveness. A worker past its timebox with no new side effect is stalled; stop it or ask the user.
 Retry by failure mode. Reduce scope after a limit or out-of-memory stop. Move a tool error to another model. A network drop or an unknown failure gets one retry only for a read-only or idempotent call. For a call that can change remote state, check the original request and the provider receipt first; do not retry an unknown effect. After two failures of one task, stop and ask the user.
 Clear conflicts first. Once conflicts are clear, triage review threads and watch CI in parallel. Classify a CI failure before a retry. A suspected flake gets one fresh build; an identical second failure is not a flake. Classify each review comment as fix, dismiss or ask by the review-comment triage reference of the installed `repo-harness-check` skill.
-Stop and ask the user when a command or result names `unknown`, `ambiguous`, `pending`, `unproven`, `identity_lost`, `reconciliation_required` or `recovery_required`, or says `inspect the same`, `inspect same`, `never replay`, `do not resend` or `do not launch again`; when a lease directory is empty or malformed; before a third review round; when a review thread concerns security, authentication, data or migrations; or when a written rule conflicts with observed state.
+Stop and ask the user when a command or result names `unknown`, `ambiguous`, `pending`, `unproven`, `identity_lost`, `reconciliation_required` or `recovery_required`, or says `inspect the same`, `inspect same`, `never replay`, `do not resend` or `do not launch again`; when a lease directory is empty or malformed; when a review thread concerns security, authentication, data or migrations; or when a written rule conflicts with observed state.
 
 Pending main push CI follows Daily Flow step 5, not the stop-and-ask rule above.
 

package/assets/reference-configs/external-tooling.md

@@ -1,72 +1,5 @@
 # External Tooling
 
-## External Source Intake P0
-
-`.ai/harness/policy.json#external_sources` is absent by default and is equivalent to the only default, `{ "version": 1, "mode": "off" }`. Refresh never auto-enables from a repository URL, installed `gh`, labels, or registry access mode.
-
-To enable one manual GitHub evidence refresh, use one exact closed selection shape. Every limit is positive. A label scan requires sorted non-empty `labels_all` and accepts a sorted optional `assignees_any` restriction. Unknown fields and provider values fail closed.
-
-```json
-{
-  "external_sources": {
-    "version": 1,
-    "mode": "manual",
-    "github": {
-      "enabled": true,
-      "repository": "owner/repository",
-      "selection": {
-        "kind": "labels",
-        "labels_all": ["ready"],
-        "assignees_any": []
-      },
-      "limits": {
-        "max_pages": 5,
-        "max_issues": 500,
-        "max_body_bytes": 65536,
-        "max_total_bytes": 1048576,
-        "deadline_ms": 30000
-      }
-    }
-  }
-}
-```
-
-For an explicitly reviewed one-shot batch, select exact Issue numbers instead of requiring provider labels or scanning the whole repository:
-
-```json
-{
-  "external_sources": {
-    "version": 1,
-    "mode": "manual",
-    "github": {
-      "enabled": true,
-      "repository": "Ancienttwo/byok-sdk",
-      "selection": {
-        "kind": "issue_numbers",
-        "issue_numbers": [102, 103, 104, 105, 106, 107, 108, 109, 110, 111]
-      },
-      "limits": {
-        "max_pages": 1,
-        "max_issues": 10,
-        "max_body_bytes": 65536,
-        "max_total_bytes": 1048576,
-        "deadline_ms": 30000
-      }
-    }
-  }
-}
-```
-
-Exact-batch refresh resolves only those Issue endpoints and fails the whole attempt if any selected Issue is missing, malformed, a pull request, or exceeds a limit. GitHub assignees, labels, and open/closed state are evidence only: they do not prove whether local work has already been dispatched. Dispatch deduplication belongs to an authenticated binding against canonical repo-harness task identity. The triage, reproduce and fix stage contract for observed issues is in [issue pipeline](issue-pipeline.md).
-
-`repo-harness external-source refresh --repo <registered-repo-id>` invokes the locally authenticated `gh` client once and records immutable observations plus an attempt receipt under the repository Git common directory. `list` performs no provider call. These records are inert evidence: they do not create or change review admission, priority, provider claims, collaboration, or Agent Runtime state.
-
-## External Source Binding WP2
-
-Binding needs an existing admitted session for the same provider issue. Save one session `selector` object from `repo-harness state board --repository-id <id> --json` as a JSON file. Then run `repo-harness external-source bind --repo <id> --source-revision <digest> --session <file>`. The command requires a strict `read_write` registry grant. The observation's provider repository and issue must match the session admission. The command persists one immutable provenance edge with the exact observation, authorization revision, session selector and admission digest.
-
-`external-source bindings` reports source, session and authorization drift without mutating work. Retired V1 receipts remain stored without a runtime reader. `external-source context` is the sole provider-content renderer and wraps canonical JSON in `[ExternalSourceUntrusted]`. A binding does not create work or admission. Human acceptance stays at PR merge; only a true `installation_blocker` may pause earlier.
-
 Generated repos route external tooling by host/runtime shape. Task-level
 skill routing lives in `docs/reference-configs/agentic-development-flow.md`.
 
@@ -75,7 +8,7 @@ skill routing lives in `docs/reference-configs/agentic-development-flow.md`.
 - `hai-stack` supplies `geju` for live, pre-contract exploration; only its frozen output enters a contract
 - Codex automation requires `health`, `check`, and `mermaid` from `~/.codex/skills`
 - `CodeGraph` is required agent readiness for code navigation and impact tracing
-- repo-harness's packaged `agent_fleet` supplies the delegation loop's global agent definitions (`explorer`, `deep-reasoner`, `fast-worker`, `gatekeeper`, `root-cause-prover`, `harness-evaluator`) for both hosts, plus the Claude-only `orchestrator`
+- repo-harness's packaged `agent_fleet` supplies the delegation loop's global agent definitions (`explorer`, `deep-reasoner`, `fast-worker`, `gatekeeper`, `root-cause-prover`, `harness-evaluator`) for both hosts
 
 Waza is Codex-first in this contract. `~/.codex/skills` is the Codex runtime
 source, while `~/.agents/skills` is only the skills CLI staging/cache path used
@@ -221,12 +154,13 @@ number of registered repos that have pending project upgrade work.
 
 The cross-review skill is **harness-owned**; its routing source lives in
 `assets/skills/repo-harness-cross-review/`. Explicit independent review uses
-the persistent fleet deep-reasoner task-agent and existing OAR host in Herdr.
+a persistent task session in Herdr: the existing OAR host runs a reviewer with
+the `deep-reasoner` role.
 The full profile installs this Skill on both hosts; generic-review file Result
 and typed Receipt own acceptance. The direct advisory runtime is retired.
 Plugin install/discovery/readiness is not a repo-harness runtime dependency;
 user-managed plugins remain untouched. Plan consultation uses persistent
-task-agent collaborators in Herdr. Review Markdown remains projection only.
+collaborator sessions in Herdr. Review Markdown remains projection only.
 
 Reverse Skill is registered from `zhaoxuya520/reverse-skill` as the recommended
 but explicit-only `reverse-skill-router`. It is not part of either install
@@ -698,8 +632,7 @@ bun add -g @colbymchenry/codegraph@1.6.2 && codegraph sync . && codegraph status
 `check-agent-tooling.sh`. The single authored source is
 `package:agents/fleet`; it ships inside the npm package and never requires a
 network fetch. The managed list is `explorer`, `deep-reasoner`, `fast-worker`,
-`deep-worker`, `gatekeeper`, `root-cause-prover`, `harness-evaluator`, and
-`orchestrator`.
+`deep-worker`, `gatekeeper`, `root-cause-prover`, and `harness-evaluator`.
 
 ### Two targets, one source
 
@@ -707,14 +640,9 @@ network fetch. The managed list is `explorer`, `deep-reasoner`, `fast-worker`,
   is installed byte-for-byte.
 - Codex: `~/.codex/agents/<agent>.toml` — generated deterministically from the
   same packaged `.md`; there is no second authored copy for Codex.
-- `orchestrator` is projected to Claude only (`CLAUDE_ONLY_AGENTS` in
-  `src/effects/terminal/task-role-profiles.ts`). The installer writes no
-  `~/.codex/agents/orchestrator.toml`, and the checker does not expect one.
-  Start it as a long-lived session with `claude --agent orchestrator`. It is
-  the coordinator and integrator seat of `repo-harness-issue-flow`
-  (`opus/xhigh`, read-only tools plus `gh` and `hc send`). It has no
-  Codex target because a Codex fleet TOML runs in a read-only sandbox without
-  network access, which cannot run `gh`.
+- The fleet holds sub-agent roles only. The orchestrator seat is not a fleet
+  role: `repo-harness seats argv orchestrator` prints its launch argv from the
+  `seats` section of `~/.repo-harness/config.json`.
 
 ### `.md` -> `.toml` mapping
 
@@ -997,7 +925,6 @@ managed files by hand:
 ~/.claude/agents/gatekeeper.md
 ~/.claude/agents/root-cause-prover.md
 ~/.claude/agents/harness-evaluator.md
-~/.claude/agents/orchestrator.md
 ~/.codex/agents/explorer.toml
 ~/.codex/agents/deep-reasoner.toml
 ~/.codex/agents/fast-worker.toml

package/assets/reference-configs/global-working-rules.md

@@ -84,7 +84,7 @@ When a task requires broad research, repo archaeology, multi-source synthesis, o
 - Implementation sub-agents may run scoped typecheck and affected tests in their own worktree. They commit early and return their check results. An evidence role whose task is a named check, such as a root-cause reproduction, still runs that check and does not commit.
 - The parent agent owns task management, conflict resolution, build and post-merge integration verification, including typecheck and affected tests.
 - After integration, the parent removes each sub-agent worktree and branch whose commits are in the task branch and whose checkout is clean. It also removes the intermediate build output and temporary files that the work created. Other deletion still needs the user.
-- The `orchestrator` fleet role is a long-lived Claude session (`claude --agent orchestrator`), not a sub-agent. The fleet projects it to Claude only. It dispatches through Herdr or MCP, never through sub-agents, and edits no product code.
+- The orchestrator seat is a long-lived session that starts from `repo-harness seats argv orchestrator`, not a sub-agent. It may call the read-only roles `gatekeeper`, `explorer` and `deep-reasoner` as sub-agents. It dispatches writers (`fast-worker`, `deep-worker`, `root-cause-prover`) and the Codex cross-review only to Herdr seats, for worktree isolation and one writer per file. It edits no product code.
 
 ## Peer Harness Collaboration
 

package/assets/reference-configs/harness-overview.md

@@ -7,7 +7,7 @@ layers hold every workflow fact, and each fact has one source. Root
 | Layer | Question | Source |
 | --- | --- | --- |
 | Flow | Who acts, when, and in what order | `repo-harness-issue-flow` skill |
-| Roles | Which seat and model fill a role | `agents/fleet/` |
+| Roles | Which seat runs which model, and which sub-agents it may call | The `seats` section of `~/.repo-harness/config.json`; sub-agent roles in `agents/fleet/` |
 | Tools | How an action runs | Herdr, the review and publication commands, `contract-worktree` |
 
 ## Flow
@@ -20,7 +20,7 @@ task state.
 - An orchestrator splits the goal into issues, dispatches work and
   integrates the results.
 - A worker claims one issue and delivers one PR.
-- An acceptor reviews one round of the PR.
+- An acceptor takes one review in one round of the PR.
 - An integrator merges. Only `repo-harness publication merge` runs this
   step.
 
@@ -37,8 +37,11 @@ rollback in the PR description. A one-time decision goes in the issue.
 
 ## Roles
 
-Roles are seats in the flow. The model choice is advice, not a gate. Any
-host can fill a seat.
+A seat is a process: the orchestrator, the advisor or a worker. A
+sub-agent is an `agents/fleet/` role that runs inside a seat process. A
+claim role (coordinator, writer, head owner, integrator, acceptor) is the
+role that a GitHub claim gives on one issue or PR. The model choice is
+advice, not a gate. Any host can fill a seat.
 
 | Role | Suggested fit | Writes |
 | --- | --- | --- |
@@ -47,9 +50,10 @@ host can fill a seat.
 | Acceptor | Fresh context, read-only; a different model family for High when available | Review threads and the acceptance record |
 | Gap reviewer | Different family from the orchestrator | Comments on drafts; no scope decision |
 
-`agents/fleet/` holds the role files. Claude projects them through
-`claude --agent <name>`. Other hosts load the same role from the issue-flow
-skill. The High tier prefers a different model family; a fresh same-family
+`repo-harness seats argv <seat>` prints the launch argv of the
+orchestrator, advisor and worker seats. `agents/fleet/` holds the sub-agent
+roles that a seat may call; the installer projects each role to Claude and
+Codex. The High tier prefers a different model family; a fresh same-family
 context is valid and records `model_relation` in the receipt.
 
 ## Tools

package/assets/reference-configs/herdr-skill-context.md

@@ -20,7 +20,7 @@ reopen an already identified Herdr terminal merely because `HC_TERMINAL_ID` is
 absent.
 
 - With `HC_TERMINAL_ID`, that value is your address. Terminals that you start
-  are your children, and children report to you with `hc send $HC_TERMINAL_ID`.
+  report to you with `hc send $HC_TERMINAL_ID`.
 - Without `HC_TERMINAL_ID`, `hc` still reaches the user's core. Start with
   `hc ls --json`. It lists all live terminals of the user, not only yours.
   Read-only discovery does not require prior task ownership.
@@ -32,7 +32,8 @@ absent.
   task and meets the requested independence requirement. A matching path or an
   idle agent alone does not authorize repurposing another task's terminal.
 - If no suitable reviewer exists, start one at the task path with
-  `hc run --bg --name <name> --cwd <task path> <template-or-agent> "<task>"`. Record the returned address.
+  `hc run --bg --no-parent --name <name> --cwd <task path> <template-or-agent> "<task>"`. Record the returned address.
+  `--no-parent` keeps the reviewer running when your program ends.
   Do not send input to terminals of another task.
 - For a visible pane, use `herdr-app do`. Split right; keep at most three
   panes per tab and create a new tab when full. `herdr-app --skill` gives the

package/assets/reference-configs/hook-operations.md

@@ -40,10 +40,10 @@ Other documents link here. They do not copy this table.
 | --- | --- | --- | --- | --- |
 | `SessionStart.default` | all sessions | Claude, Codex | `session-context` | Emit the Effective State section first, then the edit-guard-scope, architecture-debt and pending-plan sections under one budget. |
 | `PreToolUse.edit` | `Edit\|Write` | Claude, Codex | `mutation-guard` | Block an `Edit`, `Write` or Codex `apply_patch` target outside the repository, under `_ref/` or `_ops/`, or without a parseable target path. Bash writes skip it; see [Edit guard coverage](#edit-guard-coverage). |
-| `PreToolUse.subagent` | `Agent` | Claude | `return-channel` | Append the return-channel contract, standing orders and board slice to a Claude `Agent` prompt. |
+| `PreToolUse.subagent` | `Agent` | Claude | `return-channel` | Append the return-channel contract and standing orders to a Claude `Agent` prompt. |
 | `PreToolUse.bash` | `Bash` | Claude | `bash-mutation-guard` | Check literal write destinations under `_ops/`, `_ref/` or outside the repository. Unsupported shell syntax remains unchecked. |
 | `UserPromptSubmit.inbox` | all prompts | Claude, Codex | `agent-notice` | Deliver architecture debt on Codex; Claude emits nothing. |
-| `SubagentStart.context` | subagent start | Codex | `subagent-context` | Record the native role and model observation. Add the bounded child context, standing orders and board slice. |
+| `SubagentStart.context` | subagent start | Codex | `subagent-context` | Record the native role and model observation. Add the bounded child context and standing orders. |
 | `Stop.default` | session stop | Claude, Codex | `stop` | Publish the evidence checkpoint and render handoff and resume. Report protected path changes. Claude can get architecture debt. |
 
 After upgrading the package, reinstall the host adapters. Codex must trust the
@@ -66,8 +66,8 @@ Both routes above use one renderer and preserve the register text verbatim.
 The block starts with `[repo-harness:standing-orders]` and is at most 1500 UTF-8
 bytes, including the marker and any truncation line.
 A truncated block ends with `... (truncated; read .ai/harness/standing-orders.md)`.
-Claude inserts it after the return-channel text and before the board slice.
-Codex includes it in `additionalContext` before the board slice.
+Claude appends it after the return-channel text.
+Codex includes it in `additionalContext`.
 Claude skips the block when its prompt already has the marker.
 Codex adds one block to the fresh context it builds for each `SubagentStart` event.
 

package/assets/reference-configs/host-invariants.md

@@ -21,7 +21,7 @@ The grades describe repository boundaries. The delegation rows use evidence from
 | Assign a single writer per directory; never give concurrent agents overlapping write ownership. | **G** | The root agent instructions ask for one worktree per parallel writer (`CLAUDE.md:17`, `AGENTS.md:17`). No hook renders this rule, and no code acquires a directory-wide edit lease. | Root agent instructions; the active task's allowed paths and ownership brief. |
 | Run parallel writers only in separate worktrees from a clean source. Never silently drop isolation when worktree creation fails. | **G** | This is the upstream host requirement. The inspected start helper creates a Git worktree and rejects residual state with `--fresh`, but has no source-clean check in its start path (`scripts/contract-worktree.sh:523`, `scripts/contract-worktree.sh:556`, `scripts/contract-worktree.sh:588`). Do not describe the complete requirement as enforced. | Active contract's worktree boundary; `docs/researches/20260930-pi-harness-packages-extraction.md`, section 6.4. |
 | Refuse reuse when the caller requests a fresh contract worktree. | **E** | `--fresh` refuses an already-linked tree and existing metadata, path, worktree, or branch; it is an explicit option, not the default (`scripts/contract-worktree.sh:533`, `scripts/contract-worktree.sh:556`). | `contract-worktree start --fresh`. |
-| Child agents default to fresh task context and do not spawn further children. | **G** | The Codex install guidance asks for `fork_turns="none"` (`docs/reference-configs/install-profiles.md:193`). No hook or policy key sets spawn depth or validates the child's inherited transcript. `SubagentStart` records the native role observation and refuses no spawn (`src/cli/hook/subagent-context.ts:428`). | Host-native spawn configuration. |
+| Child agents default to fresh task context and do not spawn further children. | **G** | The Codex install guidance asks for `fork_turns="none"` (`docs/reference-configs/install-profiles.md:417`). No hook or policy key sets spawn depth or validates the child's inherited transcript. `SubagentStart` records the native role observation and refuses no spawn (`src/cli/hook/subagent-context.ts:428`). | Host-native spawn configuration. |
 | Accept the exact subject with its evidence, rather than treating exit code zero as acceptance. | **E** | Acceptance parsing refuses stale subject/contract evidence before checking command success; `verify-sprint` invokes receipt verification and fails that gate when verification fails (`scripts/acceptance-receipt.ts:415`, `scripts/acceptance-receipt.ts:434`, `scripts/verify-sprint.sh:1211`). Scope: the receipt-backed completion gate. | Acceptance Policy in the active contract; the `repo-harness-issue-flow` skill (`references/acceptor.md`); AcceptanceReceipt and prepared verification evidence. |
 | After an interrupted managed push/PR/merge, recover explicitly with `recover reconcile`; never automatically replay the external effect. | **E** | Managed finish/ship refuse unfinished closeout re-entry. Reconcile requires an already-landed merge/push and completes missing phases without merging/pushing again (`scripts/contract-worktree.sh:1028`, `scripts/contract-worktree.sh:1426`, `scripts/ship-worktrees.sh:611`, `scripts/ship-worktrees.sh:1539`). Normal first execution may perform the effect; before it lands, recovery uses `abort`. | `long-run-continuation.md`, Crash Recovery; the worktree-scoped closeout journal. |
 | Apply the same explicit-recovery discipline to external effects outside managed closeout. | **G** | The inspected closeout helpers do not intercept arbitrary host shell commands. A host must not replace the managed recovery protocol with its own retry loop. | `long-run-continuation.md`, Crash Recovery; the operation's authorization. |

package/assets/reference-configs/issue-pipeline.md

@@ -5,9 +5,8 @@ issue into a draft PR. The stages are triage, reproduce and fix. The host owns
 scheduling. repo-harness ships no scheduler and no automation code for this
 pipeline.
 
-Issue observation stays with `repo-harness external-source refresh|bind`. The
-local inbox stays with [heartbeat triage](heartbeat-triage.md). This contract
-adds the stop rules, the evidence handoff and the write rules.
+The local inbox stays with [heartbeat triage](heartbeat-triage.md). This
+contract adds the stop rules, the evidence handoff and the write rules.
 
 ## Stages
 

package/assets/review-hazards.v1.json

@@ -0,0 +1,57 @@
+{
+  "hazards_version": "repo-harness.review-hazards.v1",
+  "hazards": [
+    {
+      "id": "ci-config",
+      "text": "Changes a workflow or other CI configuration under `.github/`.",
+      "path_visible": true,
+      "paths": [".github/**"]
+    },
+    {
+      "id": "release-install-script",
+      "text": "Changes a release, publish, update or install script, or a package script that runs at install or release.",
+      "path_visible": false
+    },
+    {
+      "id": "container-build",
+      "text": "Changes a `Dockerfile` or another container build file.",
+      "path_visible": true,
+      "paths": ["**/Dockerfile", "**/Dockerfile.*", "**/*.Dockerfile", "**/Containerfile", "**/Containerfile.*"]
+    },
+    {
+      "id": "network",
+      "text": "Adds a network address, endpoint or telemetry.",
+      "path_visible": false
+    },
+    {
+      "id": "credentials",
+      "text": "Reads credentials, such as tokens, keys, `~/.ssh`, `~/.npmrc` or credential environment variables.",
+      "path_visible": false
+    },
+    {
+      "id": "dependency",
+      "text": "Adds or changes a dependency or a lockfile entry. A lockfile-only bump is still a hit; its source does not lower the tier.",
+      "path_visible": true,
+      "paths": [
+        "**/bun.lock",
+        "**/bun.lockb",
+        "**/package-lock.json",
+        "**/npm-shrinkwrap.json",
+        "**/yarn.lock",
+        "**/pnpm-lock.yaml",
+        "**/Cargo.lock",
+        "**/go.sum",
+        "**/poetry.lock",
+        "**/uv.lock",
+        "**/Pipfile.lock",
+        "**/Gemfile.lock",
+        "**/composer.lock"
+      ]
+    },
+    {
+      "id": "opaque-content",
+      "text": "Adds a binary, or an encoded or opaque blob, such as base64, long hex, minified or otherwise unreadable content.",
+      "path_visible": false
+    }
+  ]
+}