repo-harness 0.24.3 → 0.25.1

package/AGENTS.md

@@ -1,35 +1,19 @@
 # repo-harness
 
 ## Workflow
+- Multi-agent work follows `repo-harness-issue-flow` (`assets/skills/repo-harness-issue-flow/SKILL.md`): roles, claims, handoff, dispatch, acceptance and merge.
+- `docs/architecture/archimap.html` is the single architecture entry. It links each module to its archctx-projected capability doc in `docs/architecture/modules/`. Change boundaries only through `repo-harness-architecture`; do not hand-write other architecture docs.
+- Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
+- Only when the current task explicitly authorizes main publication, and `publication.acceptance_merge` is `on` in the policy on the PR base, is publication allowed; the skill defines who merges. Push/tag need task authorization. Deletion, credentials/permissions and release/production need user approval. An explicit no-merge instruction always wins.
+- The diff's [Review by risk](docs/reference-configs/agentic-development-flow.md#review-by-risk) tier selects independent review; the skill defines the reviewers and their model families. Changing implementation and test assertions together does not raise the tier.
+- Create task worktrees only at `/tmp/<repo>-wt-<slug>` (Windows: `os.tmpdir()`) with `repo-harness run contract-worktree start --issue <number>`, or `git worktree add` with that path. Never create one beside the main checkout (`../`). Commit or push before a reboot or a tmp cleanup. Closeout and sweep remove only merged, clean and unowned worktrees; to keep one, give it an unmerged commit, keep it dirty, or mark or lock it.
 - For non-trivial work, follow the global Progressive Due Diligence rule (P1 map, P2 trace, P3 decision) before design decisions or code edits.
 - Keep root CLAUDE.md and AGENTS.md as standalone regular files; repeat shared rules in both and keep host-specific guidance separate.
-- Read the current request and repo-local agent context, work on a branch, make bounded commits, verify once, then report the PR outcome.
+- Read the current request and repo-local agent context, work on a branch, make bounded commits, verify once, then report the PR outcome. Finish the main task first. Fix a small problem found on the way directly; for a large problem, open a GitHub issue before you work on it.
 - Read `tasks/lessons.md` at session start and apply its active lessons. Current repo state and evidence override a lesson.
-- Finish the main task first. Fix a small problem found on the way directly. For a large problem, open a GitHub issue before you work on it.
-- Ordinary tasks use the PR description: goal, scope, changes, verification, risk and rollback. No mandatory plan/contract/review/notes chain; notes are only for non-obvious decisions.
-- Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
-- Only when the current task explicitly authorizes main publication may a model squash-merge after automated checks pass and GitHub has no outstanding change requests or unresolved review threads; an explicit no-merge instruction always wins. Push/tag still require task authorization; credentials/permissions, other deletion and release/production retain their separate approval boundaries. Record authorized publication, the provider-confirmed merge SHA and parent SHA, `git revert <squash-commit>`, and the daily report. Do not create rollback tags.
-- Default worktrees are at `/tmp/<repo>-wt-<slug>` (Windows: `os.tmpdir()`). Commit or push before a reboot or a tmp cleanup.
-- Closeout and sweep remove only merged, clean and unowned worktrees. To keep one, give it an unmerged commit, keep it dirty, or mark or lock it. Details: [agentic-development-flow](docs/reference-configs/agentic-development-flow.md).
-- Automatically delete only merged, clean worktrees/branches; ask the user for every other deletion. Credentials/permissions (including confirmation bypass) and release/production operations require user approval.
-- Select independent review by the diff's [Review by risk](docs/reference-configs/agentic-development-flow.md#review-by-risk) tier: none for low, one fresh-context review for medium, gatekeeper plus cross-model review for high; ordinary steps record diagnostics without approval loops.
-- When you delegate, investigate first, then split work by write ownership. Give each parallel writer its own worktree from a clean source. Implementation sub-agents edit only their scope. They do not run build, typecheck or tests. They commit early in their own worktree and return early. In a shared checkout they do not commit; the parent commits. Evidence roles run the named check that is their task and do not commit. The parent agent owns task management, conflict resolution, build, typecheck, tests and integration. 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.
-- Model division and cross-model dispatch/review follow [Herdr Dispatch](docs/reference-configs/herdr-notify.md#herdr-dispatch).
+- Ordinary tasks use the PR description: goal, scope, changes, verification, risk and rollback. No plan, contract, review, notes or approval artifact is mandatory. Record a one-time decision in the issue.
 - GitHub operations (PRs, reviews, merges, labels, releases, comments) go only through the gh/git CLI or the GitHub API. Never use simulated browser clicks on github.com: the account can be banned.
-- When one PR changes both test assertions and implementation code, run one read-only review focused on tests bent to fit a bug (on-demand, not a restored gate; dispatch per the herdr guide).
-- `.archcontext/model/` owns architecture boundaries; read `docs/architecture/` on demand and update only real responsibility changes. Architecture diagnostics do not block work or author nested agent instructions.
-- When a branch changes a capability's responsibility, entrypoints, relations or flows, follow `repo-harness-architecture` (`assets/skill-commands/repo-harness-architecture/references/worker.md`). Handle architecture debt in the model and human prose. The archctx rolling writer publishes generated regions and the projection manifest; do not apply and commit them in a feature PR.
-- Preserve `agents/fleet/`, release checklists and downstream `assets/templates`. `.ai/harness/workflow-contract.json` is the opt-in marker. `assets/workflow-contract.v1.json` is the contract.
-- `_ops/` is ignored private operations state: never commit or agent-edit it. `_ref/` is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under `deploy/sql/`.
-
-## GitHub Issue Claims
-- Before an agent starts work on a GitHub issue, read its current state, assignees and all comments through `gh` or the GitHub API. Use pagination for comments. Check existing work claims, linked PRs and handoff notes.
-- An active claim is an assignee other than the current task owner, an open PR that links the issue, or an active claim comment that no later status comment released. If another agent or person has an active claim, do not start duplicate work. Coordinate with that owner within the authorized task scope. Take over only after an explicit handoff or user instruction. Silence, an old timestamp or a disconnected session does not release a claim.
-- When taking an unclaimed issue or an approved handoff, post a claim comment before edits, tests or worker dispatch. Use `gh issue comment <issue-url> --body-file <file>`. This rule authorizes claim and status comments for an issue within the user's task scope. It grants no other GitHub write authority.
-- Start the comment with `repo-harness issue claim`. Include `Status: active`, the agent kind and unique session or task ID, the branch, the work scope and any prior claim comment URL for a handoff. Use this identity in later status comments. A shared GitHub login is not an agent identity. Do not include secrets or private host paths.
-- Read the issue comments again after posting. Confirm the published comment URL and body. If a competing claim appeared, stop duplicate work and resolve ownership before continuing. For simultaneous claims without an explicit assignment or handoff, the earliest GitHub comment wins; break timestamp ties by comment ID. These comments coordinate agents; they are not an atomic lock and do not replace canonical task claims or leases.
-- On resume, check the current claim before continuing. Reuse the same active claim instead of posting it again. If a read or post fails, or delivery is uncertain, stop and report the failure. Read back before retrying an uncertain post.
-- Post a status comment that links the claim when the work is blocked, ready for review, complete or released. Keep a blocked or review-pending claim active. Include the PR or result when available. Release ownership explicitly on cancellation or handoff. Do not close the issue unless the task authorizes closure.
+- Preserve `agents/fleet/`, release checklists and downstream `assets/templates`. `.ai/harness/workflow-contract.json` is the opt-in marker. `assets/workflow-contract.v1.json` is the contract. `_ops/` is ignored private operations state: never commit or agent-edit it. `_ref/` is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under `deploy/sql/`.
 
 ## Code Optimization Principles
 - Identify observable conditions, controllable inputs, the invariant and the actual pressure point before changing structure.
@@ -45,6 +29,7 @@
 - For a bug fix, prefer a focused failing regression before the fix. Run only the reproducer during RED. Record a reproduction gap when the environment cannot produce it; ordinary tasks do not require RED artifacts.
 - A diff's size, a new test file, a new agent or a rebase does not by itself require a full run.
 - Use `bun run test:files <affected tests> --timeout 60000 --max-concurrency 1`; extend existing coverage before creating a new test file.
+- Test budget per PR: added test lines divided by added product lines must not exceed 2:1, and the PR adds at most one test file. A PR that adds no product lines records the exception for any added test. Measure with `git diff --numstat main...HEAD -- tests` and `git diff --numstat main...HEAD -- src scripts`; above either cap, add a `Test budget exception` PR section with the counts and why an existing test cannot cover the behavior.
 - Select tests by observable risk and owning runtime boundary, including error/recovery paths when affected.
 - Mechanical prose changes need link/scope validation, not new product tests; do not test incidental formatting or that deleted files stay deleted.
 - Reviewers consume the recorded command, result, revision and environment; they do not rerun passing checks to claim ownership.
@@ -52,20 +37,10 @@
 - Run the full suite daily; a failure opens an automatic repair task and appears in the daily report.
 - Isolate mutable HOME, repositories and process state; use real synchronization signals and preserve complete failure output.
 - Report failed, timed-out, incomplete or omitted coverage explicitly; do not manufacture receipts, waiver files or pre-fix logs.
-- Never modify or delete test assertions just to make tests pass; justify every necessary test change item by item in the PR description.
+- Never modify or delete test assertions just to make tests pass; justify every necessary test change item by item in the PR description. Remove a redundant test only when the PR names the retained test that covers the same behavior.
 - Before you write or change tests, load the `repo-harness-test` skill (`assets/skills/repo-harness-test/SKILL.md`).
 - When a local check and CI disagree, CI is the authority. Reproduce the failure with `bash scripts/check-ci.sh <lane>` before you change code; a global `repo-harness` or `repo-harness-hook` on `PATH` can hide a missing test setup.
 
-## Handoff
-- Create a checkpoint only when context/session rollover or unresolved work needs it; ordinary completion stays in the PR description.
-- Read files named in the current request before recovery context.
-- Record the goal, branch/worktree/HEAD, decisions, touched files, verification results, blockers and one exact next command.
-- Keep temporary checkpoints under ignored `.ai/harness/handoff/`; historical snapshots are not current execution authority.
-- Include evidence paths and actual command outcomes; distinguish observed state from inference.
-- Never include secrets, tokens or real environment files in handoff text.
-- On resume, verify the live checkout and source artifacts before reusing a result; `tasks/current.md` is an optional local read model.
-- Preserve dirty work and other workers' edits; hand back an ownership conflict instead of discarding their changes.
-
 ## Writing
 - Write output text (docs, PR descriptions, commit messages, reports, research notes) in ASD-STE100 Simplified Technical English: short sentences, one idea per sentence, active voice, approved-dictionary words. Write Chinese output the same way.
 - Prefer high information density: evidence first, mechanisms and business effect explained, complex reasoning allowed, no explanatory repetition. Lead with the main finding, key number or key mechanism. State known facts and supported conclusions directly, without lead-ins such as "note that", "this shows to some extent" or "it must be stressed". Put the evidence grade in the wording, not in a separate caveat.
@@ -79,9 +54,7 @@
 - Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.
 
 ## Codex
-- Own backend implementation and testing; Claude owns frontend implementation and interaction, and the parent coordinates scope and integration.
 - User-level `~/.codex/hooks.json` hooks invoke `repo-harness-hook`; its typed route registry selects one in-process handler. Operator helpers run from the package through `repo-harness run <helper>`.
 - Use `~/.codex/skills` as the runtime skill source; `~/.agents/skills` is staging/cache only. Keep `think`, `hunt`, `check` and `health` updates verified before runtime use.
 - The Codex automation profile requires runtime-provided `health`, `check` and `mermaid`; do not vendor their bodies.
-- Treat auto-compact as a fallback; prepare ignored `.ai/harness/handoff/current.md` and `resume.md` when long-task rollover is needed.
 - Keep this file short; load [development flow](docs/reference-configs/agentic-development-flow.md) and [external tooling](docs/reference-configs/external-tooling.md) only when needed.

package/CLAUDE.md

@@ -1,35 +1,19 @@
 # repo-harness
 
 ## Workflow
+- Multi-agent work follows `repo-harness-issue-flow` (`assets/skills/repo-harness-issue-flow/SKILL.md`): roles, claims, handoff, dispatch, acceptance and merge.
+- `docs/architecture/archimap.html` is the single architecture entry. It links each module to its archctx-projected capability doc in `docs/architecture/modules/`. Change boundaries only through `repo-harness-architecture`; do not hand-write other architecture docs.
+- Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
+- Only when the current task explicitly authorizes main publication, and `publication.acceptance_merge` is `on` in the policy on the PR base, is publication allowed; the skill defines who merges. Push/tag need task authorization. Deletion, credentials/permissions and release/production need user approval. An explicit no-merge instruction always wins.
+- The diff's [Review by risk](docs/reference-configs/agentic-development-flow.md#review-by-risk) tier selects independent review; the skill defines the reviewers and their model families. Changing implementation and test assertions together does not raise the tier.
+- Create task worktrees only at `/tmp/<repo>-wt-<slug>` (Windows: `os.tmpdir()`) with `repo-harness run contract-worktree start --issue <number>`, or `git worktree add` with that path. Never create one beside the main checkout (`../`). Commit or push before a reboot or a tmp cleanup. Closeout and sweep remove only merged, clean and unowned worktrees; to keep one, give it an unmerged commit, keep it dirty, or mark or lock it.
 - For non-trivial work, follow the global Progressive Due Diligence rule (P1 map, P2 trace, P3 decision) before design decisions or code edits.
 - Keep root CLAUDE.md and AGENTS.md as standalone regular files; repeat shared rules in both and keep host-specific guidance separate.
-- Read the current request and repo-local agent context, work on a branch, make bounded commits, verify once, then report the PR outcome.
+- Read the current request and repo-local agent context, work on a branch, make bounded commits, verify once, then report the PR outcome. Finish the main task first. Fix a small problem found on the way directly; for a large problem, open a GitHub issue before you work on it.
 - Read `tasks/lessons.md` at session start and apply its active lessons. Current repo state and evidence override a lesson.
-- Finish the main task first. Fix a small problem found on the way directly. For a large problem, open a GitHub issue before you work on it.
-- Ordinary tasks use the PR description: goal, scope, changes, verification, risk and rollback. No mandatory plan/contract/review/notes chain; notes are only for non-obvious decisions.
-- Keep four hard boundaries: main publication, deletion, credentials/permissions, and release/production operations.
-- Only when the current task explicitly authorizes main publication may a model squash-merge after automated checks pass and GitHub has no outstanding change requests or unresolved review threads; an explicit no-merge instruction always wins. Push/tag still require task authorization; credentials/permissions, other deletion and release/production retain their separate approval boundaries. Record authorized publication, the provider-confirmed merge SHA and parent SHA, `git revert <squash-commit>`, and the daily report. Do not create rollback tags.
-- Default worktrees are at `/tmp/<repo>-wt-<slug>` (Windows: `os.tmpdir()`). Commit or push before a reboot or a tmp cleanup.
-- Closeout and sweep remove only merged, clean and unowned worktrees. To keep one, give it an unmerged commit, keep it dirty, or mark or lock it. Details: [agentic-development-flow](docs/reference-configs/agentic-development-flow.md).
-- Automatically delete only merged, clean worktrees/branches; ask the user for every other deletion. Credentials/permissions (including confirmation bypass) and release/production operations require user approval.
-- Select independent review by the diff's [Review by risk](docs/reference-configs/agentic-development-flow.md#review-by-risk) tier: none for low, one fresh-context review for medium, gatekeeper plus cross-model review for high; ordinary steps record diagnostics without approval loops.
-- When you delegate, investigate first, then split work by write ownership. Give each parallel writer its own worktree from a clean source. Implementation sub-agents edit only their scope. They do not run build, typecheck or tests. They commit early in their own worktree and return early. In a shared checkout they do not commit; the parent commits. Evidence roles run the named check that is their task and do not commit. The parent agent owns task management, conflict resolution, build, typecheck, tests and integration. 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.
-- Model division and cross-model dispatch/review follow [Herdr Dispatch](docs/reference-configs/herdr-notify.md#herdr-dispatch).
+- Ordinary tasks use the PR description: goal, scope, changes, verification, risk and rollback. No plan, contract, review, notes or approval artifact is mandatory. Record a one-time decision in the issue.
 - GitHub operations (PRs, reviews, merges, labels, releases, comments) go only through the gh/git CLI or the GitHub API. Never use simulated browser clicks on github.com: the account can be banned.
-- When one PR changes both test assertions and implementation code, run one read-only review focused on tests bent to fit a bug (on-demand, not a restored gate; dispatch per the herdr guide).
-- `.archcontext/model/` owns architecture boundaries; read `docs/architecture/` on demand and update only real responsibility changes. Architecture diagnostics do not block work or author nested agent instructions.
-- When a branch changes a capability's responsibility, entrypoints, relations or flows, follow `repo-harness-architecture` (`assets/skill-commands/repo-harness-architecture/references/worker.md`). Handle architecture debt in the model and human prose. The archctx rolling writer publishes generated regions and the projection manifest; do not apply and commit them in a feature PR.
-- Preserve `agents/fleet/`, release checklists and downstream `assets/templates`. `.ai/harness/workflow-contract.json` is the opt-in marker. `assets/workflow-contract.v1.json` is the contract.
-- `_ops/` is ignored private operations state: never commit or agent-edit it. `_ref/` is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under `deploy/sql/`.
-
-## GitHub Issue Claims
-- Before an agent starts work on a GitHub issue, read its current state, assignees and all comments through `gh` or the GitHub API. Use pagination for comments. Check existing work claims, linked PRs and handoff notes.
-- An active claim is an assignee other than the current task owner, an open PR that links the issue, or an active claim comment that no later status comment released. If another agent or person has an active claim, do not start duplicate work. Coordinate with that owner within the authorized task scope. Take over only after an explicit handoff or user instruction. Silence, an old timestamp or a disconnected session does not release a claim.
-- When taking an unclaimed issue or an approved handoff, post a claim comment before edits, tests or worker dispatch. Use `gh issue comment <issue-url> --body-file <file>`. This rule authorizes claim and status comments for an issue within the user's task scope. It grants no other GitHub write authority.
-- Start the comment with `repo-harness issue claim`. Include `Status: active`, the agent kind and unique session or task ID, the branch, the work scope and any prior claim comment URL for a handoff. Use this identity in later status comments. A shared GitHub login is not an agent identity. Do not include secrets or private host paths.
-- Read the issue comments again after posting. Confirm the published comment URL and body. If a competing claim appeared, stop duplicate work and resolve ownership before continuing. For simultaneous claims without an explicit assignment or handoff, the earliest GitHub comment wins; break timestamp ties by comment ID. These comments coordinate agents; they are not an atomic lock and do not replace canonical task claims or leases.
-- On resume, check the current claim before continuing. Reuse the same active claim instead of posting it again. If a read or post fails, or delivery is uncertain, stop and report the failure. Read back before retrying an uncertain post.
-- Post a status comment that links the claim when the work is blocked, ready for review, complete or released. Keep a blocked or review-pending claim active. Include the PR or result when available. Release ownership explicitly on cancellation or handoff. Do not close the issue unless the task authorizes closure.
+- Preserve `agents/fleet/`, release checklists and downstream `assets/templates`. `.ai/harness/workflow-contract.json` is the opt-in marker. `assets/workflow-contract.v1.json` is the contract. `_ops/` is ignored private operations state: never commit or agent-edit it. `_ref/` is an ignored reference cache; cite influential revisions. Follow deploy SQL policy, otherwise use ascending 4-digit files under `deploy/sql/`.
 
 ## Code Optimization Principles
 - Identify observable conditions, controllable inputs, the invariant and the actual pressure point before changing structure.
@@ -45,6 +29,7 @@
 - For a bug fix, prefer a focused failing regression before the fix. Run only the reproducer during RED. Record a reproduction gap when the environment cannot produce it; ordinary tasks do not require RED artifacts.
 - A diff's size, a new test file, a new agent or a rebase does not by itself require a full run.
 - Use `bun run test:files <affected tests> --timeout 60000 --max-concurrency 1`; extend existing coverage before creating a new test file.
+- Test budget per PR: added test lines divided by added product lines must not exceed 2:1, and the PR adds at most one test file. A PR that adds no product lines records the exception for any added test. Measure with `git diff --numstat main...HEAD -- tests` and `git diff --numstat main...HEAD -- src scripts`; above either cap, add a `Test budget exception` PR section with the counts and why an existing test cannot cover the behavior.
 - Select tests by observable risk and owning runtime boundary, including error/recovery paths when affected.
 - Mechanical prose changes need link/scope validation, not new product tests; do not test incidental formatting or that deleted files stay deleted.
 - Reviewers consume the recorded command, result, revision and environment; they do not rerun passing checks to claim ownership.
@@ -52,20 +37,10 @@
 - Run the full suite daily; a failure opens an automatic repair task and appears in the daily report.
 - Isolate mutable HOME, repositories and process state; use real synchronization signals and preserve complete failure output.
 - Report failed, timed-out, incomplete or omitted coverage explicitly; do not manufacture receipts, waiver files or pre-fix logs.
-- Never modify or delete test assertions just to make tests pass; justify every necessary test change item by item in the PR description.
+- Never modify or delete test assertions just to make tests pass; justify every necessary test change item by item in the PR description. Remove a redundant test only when the PR names the retained test that covers the same behavior.
 - Before you write or change tests, load the `repo-harness-test` skill (`assets/skills/repo-harness-test/SKILL.md`).
 - When a local check and CI disagree, CI is the authority. Reproduce the failure with `bash scripts/check-ci.sh <lane>` before you change code; a global `repo-harness` or `repo-harness-hook` on `PATH` can hide a missing test setup.
 
-## Handoff
-- Create a checkpoint only when context/session rollover or unresolved work needs it; ordinary completion stays in the PR description.
-- Read files named in the current request before recovery context.
-- Record the goal, branch/worktree/HEAD, decisions, touched files, verification results, blockers and one exact next command.
-- Keep temporary checkpoints under ignored `.ai/harness/handoff/`; historical snapshots are not current execution authority.
-- Include evidence paths and actual command outcomes; distinguish observed state from inference.
-- Never include secrets, tokens or real environment files in handoff text.
-- On resume, verify the live checkout and source artifacts before reusing a result; `tasks/current.md` is an optional local read model.
-- Preserve dirty work and other workers' edits; hand back an ownership conflict instead of discarding their changes.
-
 ## Writing
 - Write output text (docs, PR descriptions, commit messages, reports, research notes) in ASD-STE100 Simplified Technical English: short sentences, one idea per sentence, active voice, approved-dictionary words. Write Chinese output the same way.
 - Prefer high information density: evidence first, mechanisms and business effect explained, complex reasoning allowed, no explanatory repetition. Lead with the main finding, key number or key mechanism. State known facts and supported conclusions directly, without lead-ins such as "note that", "this shows to some extent" or "it must be stressed". Put the evidence grade in the wording, not in a separate caveat.
@@ -79,7 +54,6 @@
 - Avoid unnecessary secondary labels and descriptions. Let the layout do the explaining.
 
 ## Claude Code
-- Own frontend implementation and interaction; Codex owns backend implementation and testing, and the parent coordinates scope and integration.
 - Use Claude Code's available tools within granted permissions; changes to tool grants, hooks or confirmation bypass require approval of the exact change.
 - User-level `~/.claude/settings.json` hooks invoke `repo-harness-hook`; its typed route registry selects one in-process handler. Operator helpers run from the package through `repo-harness run <helper>`.
 - Write comments, commits and PR text from the final diff; comments explain non-obvious reasons, and PRs describe final behavior and material rationale.

package/README.md

@@ -43,7 +43,7 @@ files let Claude and Codex resume work across sessions.
 
 ### 1. Install the CLI
 
-Prerequisites: a Git working tree, `bun`, and usable `herdr` >=0.9.3 for host readiness; macOS/Linux also require `bash`,
+Prerequisites: a Git working tree, `bun`, and usable `herdr` >=0.9.5 for host readiness; macOS/Linux also require `bash`,
 while Windows requires Git for Windows (including its Bash and `usr/bin`
 tools). `jq` is optional. No Node.js required — the installer uses Bun >=
 1.4.0 as the runtime, installing or upgrading Bun first when needed.
@@ -79,6 +79,37 @@ endpoints. See [runtime cutover](https://github.com/Ancienttwo/repo-harness/blob
 repo-harness install
 ```
 
+Pi is an optional host under the default `--target both`. When `pi` is on
+PATH, install and update register the installed repo-harness directory with
+`pi install <package-directory>`. An existing user package entry is retained.
+Missing Pi skips this step. Preview with `repo-harness install --dry-run --json`.
+The minimum Pi version is [MIN_PI_VERSION](src/pi/compat.ts); there is no upper bound.
+`repo-harness setup check` and `repo-harness update --check` report the version,
+path resolver capability, package entry and skill projection.
+
+Catalog skills use `${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}/skills` and the
+same profile selection and ownership rules as the other hosts. Uninstall removes
+only owned package entries and unchanged owned skills. Package commands use Pi's
+CLI; repo-harness does not write Pi settings, credentials or trust files.
+Pi covers session context, agent notices, edit/write, bash and Stop hooks.
+It has no fleet roles or subagent hooks. PowerShell, `!`/`!!` user shell,
+other extensions' file writes and third-party MCP writes are outside this coverage.
+
+DSH (DeepSeek Harness) is a package host. repo-harness ships a Cordis plugin
+and a bundle patch; DSH manages the installation. Load the plugin with
+`dsh plugin add link:<repo-harness package directory>`, or with
+`dsh plugin add repo-harness@<version>` after release. The plugin needs Bun on
+`PATH`; it starts this package's `dist/hook-entry.js`. It maps native `write`,
+`edit` and `bash` calls to the typed guards, delivers session context through
+the first agent step, and records Stop at the turn boundary. It disables
+itself in a repository without `.ai/harness/workflow-contract.json`. MCP
+writes, `pwsh`, `!` user commands and writes from other plugins stay outside
+this boundary. DSH already reads `AGENTS.md` and `~/.agents/skills`; the
+plugin does not change those paths. `repo-harness doctor` and
+`repo-harness setup check` report whether a DSH profile declares the bundle,
+and list the external skills in the shared agents root. repo-harness does not
+write the DSH profile.
+
 On Windows, keep Git for Windows on the install/update `PATH`. That explicit
 ceremony validates and pins `git.exe`, its matching `bash.exe`/`usr/bin`, and
 the install account's absolute `TEMP` directory plus native `System32` tools in the OS account's
@@ -109,26 +140,24 @@ or refreshed. It never creates an application stack; new projects and modules us
 
 ```bash
 repo-harness init
-bash scripts/check-task-workflow.sh
 bun test
 ```
 
 ### Success looks like this
 
-Init writes repo-local files and two files under `HOME`: the repo registry
-entry and, when verification runs, the global Codex handoff packet under
-`~/.codex/handoffs/`. It writes no install-managed host files. When the
+Init writes repo-local files and one file under `HOME`: the repo registry
+entry. It writes no install-managed host files. When the
 required Herdr skill or the architecture projection preference is missing, init
 reports a skipped step that names `repo-harness update`. repo-harness supplies tools and evidence; the Bot
 decides what to schedule.
 
 Apply ends with `=== Migration Report ===`, naming where generated hook behavior
 comes from, the user-level `~/.claude/settings.json` and `~/.codex/hooks.json`
-adapter target, the repo-local surfaces created or refreshed, the
-`.ai/harness/scripts/*` helper runtime, and an `--- External Tooling ---`
-readiness block. Stable intent then lives in `docs/spec.md`, execution state in
-`plans/` and `tasks/`, resume state in `.ai/harness/handoff/`. If the dry run
-looks wrong, stop and read
+adapter target, the repo-local surfaces created or refreshed, and an
+`--- External Tooling ---` readiness block. Stable intent then lives in
+`docs/spec.md` and `docs/prds/`, task and resume state in the GitHub issue,
+its claim comments and the PR. If the dry run looks wrong, stop and
+read
 [`hook-operations.md`](docs/reference-configs/hook-operations.md) first.
 
 ### Update and remove
@@ -138,10 +167,10 @@ repo-harness update          # reconcile CLI, mandatory deps, profile tooling, a
 repo-harness update --check  # read-only repair guidance, no writes
 repo-harness upgrade         # check retired leftovers; no writes
 repo-harness upgrade --apply # back up and remove only proven owned leftovers
+repo-harness upgrade decide --keep <path> # record an operator decision for a report-only project item
+repo-harness upgrade --registered # preview project refresh for every registered repo; no writes
 repo-harness uninstall --dry-run # preview owned user configuration cleanup
 repo-harness uninstall           # remove owned configuration; preserve user changes/history
-repo-harness mcp uninstall --dry-run # preview independent MCP setup cleanup
-repo-harness mcp uninstall --services-stopped # after stopping all MCP HTTP services
 ```
 
 `update` and `setup check` print one leftover count. `update` does not apply
@@ -184,10 +213,9 @@ release line have no supported historical proof and remain report-only.
 ## Why repo-harness
 
 - **File-backed sessions, not chat memory.** Separate Claude and Codex sessions
-  stay coordinated through the repo. `SessionStart` injects the prior session's
-  resume packet, and `Stop` writes the handoff and resume views. A session can
-  end mid-task and the next one resumes the exact next step, blockers, and
-  changed files without re-deriving them.
+  stay coordinated through the repo and its GitHub issue and PR. A session can
+  end mid-task. The next one reads the issue, the latest claim status and the
+  PR, and resumes the exact next step without re-deriving it.
 - **Token-lean by design.** Instead of grep-and-read loops that re-scan the repo
   every session, the harness leans on a pre-built CodeGraph index for structural
   queries and on progressive context loading: a stable ~12KB root context plus
@@ -203,9 +231,8 @@ In an adopted repo, the surface area is intentionally small:
 | Surface | Purpose |
 | --- | --- |
 | `docs/spec.md` and `docs/reference-configs/` | Shared standards and stable product intent that every agent session can read. |
-| `plans/`, `plans/prds/`, and `plans/sprints/` | Optional planning context and historical work records. |
-| `tasks/contracts/`, `tasks/reviews/`, and `.ai/harness/checks/` | Existing closeout and recovery records retained during the lifecycle removal. |
-| `.ai/harness/handoff/` and `tasks/current.md` | Session journal and resumable status, derived from workflow artifacts instead of chat memory. |
+| `docs/prds/` | Product intent and optional design briefs. |
+| `tasks/lessons.md` | The one local lesson ledger. Task identity and history stay in the issue and PR. |
 
 ## Task Authority
 
@@ -227,13 +254,13 @@ callers while the contract lifecycle is removed.
 
 | | |
 | --- | --- |
-| **File-backed sessions** | Plans, contracts, checks, and handoffs live in the repo, so a new session resumes from artifacts instead of a chat thread |
+| **File-backed sessions** | Issues, PRs, checks, and handoffs live in the repository, so a new session resumes from artifacts instead of a chat thread |
 | **Typed hook runtime** | 6 public routes (Claude 5, Codex 5), each bound to exactly one typed in-process handler, with fail-closed guards at the edit boundary |
 | **Issue → PR → Review** | One task authority with bounded changes, recorded verification and review evidence |
 | **Session handoff** | Record the issue, branch, evidence and next action so another agent can continue |
 | **Progressive context loading** | A ~12KB stable root context plus ~1KB capability contracts loaded only for the files actually being touched |
 | **CodeGraph integration** | Structural queries (callers, callees, definitions) answered from a pre-built index instead of repeated grep-and-read passes |
-| **MCP planner sidecar** | ChatGPT reads real repo state and writes PRD/Sprint/Goal artifacts; Codex executes them, with no default source-code write access |
+| **MCP planner sidecar** | A local MCP client reads real repo state over stdio and writes PRD artifacts, with no default source-code write access |
 | **Claude + Codex alignment** | One user-level adapter contract, one workflow contract, and one set of repo-local artifacts shared by both hosts |
 
 ## How It Works
@@ -242,7 +269,7 @@ callers while the contract lifecycle is removed.
    typed hook handlers, the operator-helper asset, workflow contract, tests, and
    release gate.
 2. **Target repo contract**: `repo-harness init` or migration writes repo-local
-   files such as `docs/spec.md`, `plans/`, `tasks/`, `.ai/context/`,
+   files such as `docs/spec.md`, `docs/prds/`, `tasks/lessons.md`, `.ai/context/`,
    `.ai/harness/`, helper scripts, and `.ai/hooks/`.
 3. **Host adapters**: user-level `~/.claude/settings.json` and
    `~/.codex/hooks.json` route Claude/Codex events into `repo-harness-hook`.
@@ -261,8 +288,7 @@ Handler details and policy modes:
 ## Task Workflow
 
 The GitHub issue and PR carry task identity, claims, status and dependencies.
-Optional plans explain the work. The retained contract closeout helpers serve
-old records until that lifecycle is retired.
+There is no local plan, sprint, contract, review or notes artifact.
 
 ```mermaid
 flowchart TD
@@ -285,12 +311,10 @@ flowchart TD
 For long-running product loops, keep discovery and engineering-plan judgment with
 the parent agent before Codex loops on execution: `geju` opens the pre-contract
 frame, the parent completes P1/P2/P3 and freezes the accepted direction into an
-upper-layer PRD under `plans/prds/` and an ordered sprint backlog under
-`plans/sprints/`, then a Codex Goal points at that sprint file. The PRD stays the
-upper source of truth and the backlog is the durable execution queue, so a
+upper-layer PRD under `docs/prds/`, then orders GitHub issues through
+`repo-harness-issue-flow`. The issue and PR are the durable execution queue, so a
 resumed Goal session never reinterprets the original chat. See
-[`agentic-development-flow.md`](docs/reference-configs/agentic-development-flow.md)
-and [`workflow-orchestration.md`](docs/reference-configs/workflow-orchestration.md).
+[`agentic-development-flow.md`](docs/reference-configs/agentic-development-flow.md).
 
 ## Work Across Sessions
 
@@ -305,12 +329,13 @@ repo-harness fleet board --json
 ```
 
 The board reads retained task, Lease, publication, inbox and runtime evidence.
-It does not claim work or create an Engineer binding. Existing completion and
-cleanup helpers remain for existing contract lifecycle callers.
+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
-planning, and [repo-harness-check](assets/skill-commands/repo-harness-check/SKILL.md)
+PRD or Goal work, [repo-harness-issue-flow](assets/skills/repo-harness-issue-flow/SKILL.md)
+for issue backlog splitting and dispatch, and [repo-harness-check](assets/skill-commands/repo-harness-check/SKILL.md)
 for scope and recorded verification.
 
 ### Refactor recommendations
@@ -330,7 +355,6 @@ accepted suggestion goes through the normal plan and pull request workflow.
 ```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 historical-bindings --repo <id>  # retired V1 records only
 repo-harness external-source bindings  # binding edges and current drift attention
 ```
 
@@ -352,8 +376,8 @@ an explicit `execution_mode`: `contract` or `inline`. The mode is part of the
 approved admission digest; changing it requires new approval. Do not create an
 approval from these examples: actor IDs and authorization references are binding
 data, not authentication. Select the resulting active grant and policy digests
-below, and supply the current immutable issue claim. A contract or plan file
-cannot grant permission. A user waiver requires a separate upstream-authorized
+below, and supply the current immutable issue claim. A local plan or contract
+file cannot grant permission. A user waiver requires a separate upstream-authorized
 decision; waiver eligibility in an admission does not grant one.
 
 See [the control Bot boundary](docs/control-bot-boundary.md) for the integration contract.
@@ -368,6 +392,10 @@ In the Claude desktop app without Herdr, add `--launch app-terminal` and omit `-
 
 A dedicated linked checkout hosts one fleet `deep-reasoner` task-agent in the addressed Herdr session for at most three repair rounds. Default selection uses the owner’s opposite harness; `--harness` explicitly selects Claude or Codex. Only a missing executable before start allows a reported fallback. File Results pass domain binding/finding checks and the generic-review Receipt writer/verifier before close. Terminal history is observation. Claude uses an exact result-file allowlist plus mutation fingerprints; production OS write isolation and complete large-packet ingestion remain unverified.
 
+### Bot merge
+
+A local Herdr Bot runs `repo-harness publication merge` in its shell. A cloud-only Bot runs the same command in a sandbox that has repo-harness, a working `gh auth` and a checkout. It merges only when `publication.acceptance_merge` is `on` in the policy on the PR base, and it needs strict required checks and enforce_admins on the default branch. A Bot record does not grant merge permission. See [the control Bot boundary](docs/control-bot-boundary.md#bot-modes-and-merge).
+
 ## Hooks
 
 The installed adapter binds 6 public hook routes: Claude installs 5 and Codex
@@ -395,24 +423,40 @@ Full playbook:
 
 ## Local Human Control Board
 
-Run the observe-only operator view on the same machine as the adopted
-repositories:
+Run the operator console on the same machine as the adopted repositories:
 
 ```bash
 repo-harness operator serve
 ```
 
-The command binds to loopback only and prints the local URL. The browser shows
-the canonical Fleet summary, an attention-first worklist, a resident task
-detail pane, and degraded snapshot states. The board is read-only. It does not
-send messages, acquire tasks, change workflow state, start agents, or show
-repository paths.
+The command binds to loopback only and prints the local URL. The console has
+these pages: the development board with its task drawer, repositories, Agents,
+Skills, Hooks, tools, architecture and system status. The theme follows the
+system until you pick one. The language follows your saved choice, then the browser language.
+
+The approved design allows three bounded writes and nothing else. They open in
+this order: local agent config in `~/.repo-harness/config.json`, docs sessions
+that return changes as a Draft PR, and worktree cleanup. Green worktree cleanup
+also has a terminal form:
+
+```bash
+repo-harness worktrees list            # add --json for ids and selection digests
+repo-harness worktrees clean --ids <id,...> --expected-digest <digest>
+```
+ Each write passes an origin check, a write token and a
+precondition check, and is audited before it runs. Host projection (install,
+update, profile switch), registry cleanup and CLI uninstall stay commands that
+you run in a terminal. The console does not send messages to coding sessions,
+stop them or dispatch work; dispatch stays Bot → CLI → herdr. Browser payloads
+do not contain secrets or absolute paths. Product scope:
+[`docs/prds/20261026-2310-operator-console-uiux.prd.md`](docs/prds/20261026-2310-operator-console-uiux.prd.md);
+UX: [`docs/prds/DESIGN-operator-console-uiux.md`](docs/prds/DESIGN-operator-console-uiux.md).
 
 Read committed architecture facts or export a module review prompt:
 
 ```bash
 repo-harness module list --json
-repo-harness module review-prompt capability.runtime-harness.engineer-bindings --json
+repo-harness module review-prompt capability.runtime-harness.task-agent-host --json
 ```
 
 The prompt uses HEAD content. It reports uncommitted paths and their content
@@ -423,42 +467,29 @@ shards arrive. Diff mode requires both `--base <rev>` and `--head <rev>`.
 
 ## MCP Connector
 
-As an optional sidecar, `repo-harness mcp` exposes workflow artifacts to MCP
-clients through the default `planner` profile. ChatGPT reads real repo state and
-moves an idea through PRD, checklist Sprint, and task goal handoff artifacts —
-with no default source-code write access, arbitrary shell execution, or default
-runner. The task owner directs an explicitly addressed Herdr agent to execute the task goal.
+As an optional sidecar, `repo-harness mcp serve` exposes workflow artifacts to a
+local MCP client over stdio through the default `planner` profile or the
+`executor` profile. The client reads real repo state and writes PRDs under
+`docs/prds/`. It has no default source-code write access, no shell and no runner. The
+task owner directs an explicitly addressed Herdr agent to execute the task goal.
 
 ```bash
-repo-harness mcp setup chatgpt --repo .
-repo-harness mcp serve --repo . --transport http --host 127.0.0.1 --port 8765 --profile planner
+repo-harness mcp serve --repo . --profile planner
+repo-harness mcp doctor --repo .
 ```
 
-Expose that local server through an HTTPS tunnel, register the `/mcp` URL, and
-the human workflow is:
-
-1. ChatGPT reads repo-harness workflow files through MCP.
-2. ChatGPT writes a PRD with `write_prd_from_idea`.
-3. ChatGPT writes a checklist Sprint with `write_checklist_sprint`.
-4. ChatGPT prepares `.ai/harness/handoff/task-goal.md` with `prepare_task_goal_from_sprint`.
-5. The task owner sends the generated execution prompt to an explicitly addressed Herdr agent and stages each completed Sprint phase.
-
-General repo reader/writer tools, snapshot and index consistency, server
-profiles, and the opt-in dev runner:
-[`general-repo-mcp.md`](docs/reference-configs/general-repo-mcp.md). Direct-coding
-profile: [`chatgpt-coding-mcp.md`](docs/reference-configs/chatgpt-coding-mcp.md).
+General repo reader/writer tools, snapshot and index consistency, and server profiles:
+[`general-repo-mcp.md`](docs/reference-configs/general-repo-mcp.md).
 Index-stale, CodeGraph-down, and rollback operations:
 [`general-repo-mcp-codegraph.md`](deploy/runbooks/general-repo-mcp-codegraph.md).
 
 ## Reviewing Work
 
-Start with `tasks/reviews/<task>.review.md`. Its `## Human Review Card` is the
-one-screen decision surface: verdict, change type, intended vs actual files,
-commands passed, external acceptance, residual risk, reviewer action, and
-rollback. Then inspect the active contract, the latest trace in
-Verification Plan execution records, and the changed files. Accept only when the
-review recommends pass, the card verdict is pass, and external acceptance is
-pass, `not_required`, or an explicit override.
+Start with the PR description. It is the one-screen decision surface: goal,
+scope, changes, commands passed, external acceptance, residual risk and rollback.
+Then inspect the changed files, the latest trace in Verification Plan execution
+records, and the checks. Accept only when the checks pass and external acceptance
+is pass, `not_required`, or an explicit override.
 
 Execution facts and acceptance are separate authorities: a passing
 `verify-contract` run proves a command ran, not that the work is accepted.
@@ -468,15 +499,11 @@ Agents read source artifacts before derived summaries:
 
 | Agent reads first | Human reviews first |
 | --- | --- |
-| Current user prompt and referenced files | `tasks/reviews/<task>.review.md` Human Review Card |
+| Current user prompt and referenced files | PR description |
 | `AGENTS.md` / `CLAUDE.md` | Changed files and diff |
-| Active plan in `.ai/harness/active-plan` | Active contract allowed paths and exit criteria |
-| Active contract in `tasks/contracts/` | Verification Plan execution records and run trace |
-| Latest handoff in `.ai/harness/handoff/` | Residual risks and rollback |
-
-`tasks/current.md` is an ignored local orientation snapshot, not a tracked file.
-If it disagrees with the active plan, contract, review, checks, or handoff, the
-source artifacts win.
+| The GitHub issue and PR | Verification Plan execution records and run trace |
+| Latest claim status comment on the issue | Residual risks and rollback |
+If it disagrees with the issue, PR, checks, or handoff, the source artifacts win.
 
 Runtime-heavy validators (Unity, browser E2E, mobile simulators, hardware rigs,
 staging smoke tests) can publish external verification manifests under the
@@ -498,14 +525,15 @@ control context loading. They do not add a host permission boundary.
 | --- | --- | --- |
 | `repo-harness` | Bot | Route explicit harness actions |
 | `repo-harness-check` | Bot | Plan scoped work, review plans, assess recorded checks |
-| `repo-harness-product` | Bot | Requested PRD, Sprint or Goal preparation |
+| `repo-harness-product` | Bot | Requested PRD drafting or Goal preparation |
+| `repo-harness-issue-flow` | Bot | Issue and PR driven multi-agent development: split by module, dispatch workers, follow PRs and CI |
 | `repo-harness-ship` | Bot | Explicit publication and cleanup decisions |
 | `obsidian-memory` | Bot | Explicit memory recall or persistence |
 | `repo-harness-cross-review` | Bot | Generic review; direct advisory runtime retired |
-| `repo-harness-chatgpt` | Bot | Explicit integration mode and advisory decisions |
 | `repo-harness-setup` | Worker | Assigned install, migration, repair or scaffold |
 | `repo-harness-test` | Worker | Source tests and real fixtures |
 | `repo-harness-architecture` | Worker | Assigned model, projection or diagram work |
+| `repo-harness-archimap` | Worker | Draw or refresh the human-facing architecture map `docs/architecture/archimap.html` |
 | `windows-python-first` | Worker | Native Windows file, text and shell work through Python |
 
 Planning is merged into `repo-harness-check`. No separate planning alias remains.
@@ -540,7 +568,7 @@ paths are symlink-backed runtime entrypoints rebuilt by
 the npm unpublished-version preflight, then runs the `release` lane: the
 expensive-gated tests and the tarball install smoke. It is not a second full
 suite and not the CI gate; a release depends on green CI for the release SHA.
-Runtime routing regressions stay in affected tests. The old routing eval gate is retired.
+Runtime routing regressions stay in affected tests. The old routing eval gate is retired. The skill-routing aggregate in `evals/skill-routing/routing-aggregate.json` is advisory evidence, not a merge gate: the provider harness passes the raw corpus prompt with no routing preamble, so the run measures direct model answers, not skill discovery. The aggregate sets `advisory: true` and records the reason; its `overall_pass` and floors stay reported metrics. A follow-up will add the routing preamble and reconsider gating.
 
 ```bash
 bun run check:ci                    # the whole gate
@@ -568,7 +596,6 @@ dependencies.
 | [herdr](https://herdr.dev/) | Required peer-terminal runtime: notification dispatch, peer collaboration, and hosting the persistent acceptance reviewer | Externally installed binary, checksum-pinned in `.ai/harness/policy.json`; replaces the retired tmux runtime |
 | [`reverse-skill-router`](https://github.com/zhaoxuya520/reverse-skill) | Routes reverse-engineering and security tasks to specialist playbooks | Recommended explicit-only Skill (`--with-reverse-skill`); not profile-selected because upstream's target-mention authorization assumption requires independent scope review |
 | CodeGraph (`@colbymchenry/codegraph`) | Symbol-aware navigation, impact tracing, and readiness checks for this self-host repo | Dev dependency in this repo; generated repos stay global-MCP-first unless policy opts in |
-| [Oracle](https://github.com/steipete/oracle) by [Peter Steinberger](https://x.com/steipete) (`@steipete/oracle`, MIT) | Default GPT Pro / ChatGPT Web browser consult engine that the `chatgpt-browser` Oracle provider shells out to for `gptpro` consults | Externally-resolved binary (`--oracle-bin`, `REPO_HARNESS_ORACLE_BIN`, `node_modules/.bin`, or `PATH`); never auto-downloaded, and a missing binary is a hard `ORACLE_NOT_INSTALLED` failure |
 | OpenAI Codex | Primary execution agent for repo-local implementation, verification, and GitHub contributor attribution when a commit materially includes Codex-authored work | External agent runtime; attribution is an explicit commit trailer, not hidden hook automation |
 
 ### GitHub Contributor Attribution
@@ -585,8 +612,8 @@ repo-harness commit scripts or hooks unless that repo adopts the same policy.
 
 ## Current Release
 
-- npm package: `repo-harness@0.24.3`
-- Generated workflow stamp: `repo-harness@0.24.3+template@0.24.3`
+- npm package: `repo-harness@0.25.1`
+- Generated workflow stamp: `repo-harness@0.25.1+template@0.25.1`
 - GitHub repository: `Ancienttwo/repo-harness`
 - Release notes and history: [`docs/CHANGELOG.md`](docs/CHANGELOG.md)
 

package/SKILL.md

@@ -9,17 +9,18 @@ when_to_use: "repo-harness"
 Bot entrypoint. Resolve scope, worker ownership and the authorized outcome.
 When acting as a PM Bot, use [the shared PM boundary](references/pm-boundary.md).
 The PM coordinates work. Coding agents own source edits, tests and repairs.
+GrokBot init: [bot onboarding](docs/bot-onboarding.md).
 This role applies to Grok, Hermes, Dot and other Bot hosts. It does not restrict
 an explicitly assigned coding worker or a direct development session.
 Use `repo-harness state resolve --json` when active harness state is needed.
 Treat the returned state as authority; load only the files it names.
 Load the required `herdr` skill before controlling Herdr panes or agents.
-Only an agent inside a Herdr pane may run those control commands.
+Discover panes by task path, then use explicit targets.
 
 1. **setup** — bind the mode and target repo, then assign `repo-harness-setup`.
 2. **plan** — use `repo-harness-check` for scoped design or plan review.
-   Use `repo-harness-product` only for requested PRD, Sprint or Goal work.
-3. **execute** — assign a bounded brief and owning paths. Load worker techniques
+   PRD or Goal: `repo-harness-product`. Issues: `repo-harness-issue-flow`.
+3. **execute** — assign a [worker brief](assets/reference-configs/herdr-notify.md#worker-briefs). Load worker techniques
    from `repo-harness-test` or
    [`repo-harness-architecture`](assets/skill-commands/repo-harness-architecture/SKILL.md)
    only when needed.