orchestrator-workflow 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -5,6 +5,335 @@ All notable changes to `orchestrator-workflow` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.26.0] - 2026-08-30
+
+### Added
+
+- The orchestrator now writes a per-worktree run pointer, `.ai/run`: a plain
+  text file whose first non-empty line is the absolute path of the run
+  directory, one written in every repository or worktree a run touches
+  (`SKILL.md` Run state, step 1, and all three Harness notes bullets;
+  `agents-md-section.md` Run state gained the matching bullet). For a run
+  spanning more than one repository, `00-goal.md` now also carries one keyed
+  `run-base[<repo-basename>]` marker per repository alongside the existing
+  unkeyed one, exact form `<!-- solution-acceptance: run-base[<repo-basename>]
+  = <sha> -->`; the shipped template line uses the placeholder key
+  `<repo-basename>` and value `<sha>` as a documentation example. Both are
+  written for a new consumer: the `.ai/run` pointer and the keyed marker are
+  read by grounding-mcp's `ow-run-completeness` reader, released as
+  `@lannguyensi/grounding-mcp` 0.9.0 (agent-grounding task
+  `design/ow-run-pointer-binding`, agent-tasks 43a7ef58, PR #198). The
+  reader resolves a run through the pointer first and falls back to scanning
+  the repository's own `.ai/runs/` (newest by name) only when no pointer file
+  exists, so kits and repos without the pointer keep working exactly as
+  before; the run-base marker's own date-heuristic fallback for a `TODO`
+  value is a separate mechanism and is unchanged. `README.md` ("What gets
+  installed") and `INSTALL-AGENT.md`
+  ("Write surface" and the manual scaffold list) now note that `.ai/run`
+  should be added to the repository's `.gitignore` (the installer does not
+  edit `.gitignore` itself). Pinned by new tests in
+  `test/template-markers.test.ts` (the keyed placeholder line's exact text,
+  its whole-line-comment shape, its position directly below the unkeyed
+  marker, and that the existing unkeyed `run-base` regex still matches
+  exactly once) and a new `test/docs-consistency.test.ts` describe block
+  (the pointer contract's phrases in SKILL.md Run state, the exact keyed
+  example string, step 1, each of the three Harness notes bullets
+  individually, the agents-md-section bullet, and the README/INSTALL-AGENT
+  gitignore notes). Anchors in `docs/okf/*.md` that cite line ranges in
+  `SKILL.md`, `test/docs-consistency.test.ts`, and
+  `test/template-markers.test.ts` drifted out of range because of the line
+  shifts this change introduces; those anchors were re-pointed in the same
+  PR, and `run-state-lifecycle-and-markers.md` gained a section documenting
+  the pointer and the keyed marker.
+- Two review rounds on the run-pointer change above corrected inaccurate
+  claims and hardened the pinning tests. `SKILL.md` Run state now states the
+  pointer contract as a short lead sentence plus three bullets (what the
+  pointer's content is, when to write, overwrite, and remove it, and to
+  make sure it is ignored before writing it), followed by a separate
+  paragraph on how the run-completeness reader uses it: pointer first,
+  falling back to that repository's own `.ai/runs/` (the run there that
+  sorts newest by directory name) only when no pointer file exists, with a broken pointer rejected outright
+  rather than falling back; the exact accept/reject rules are left to the
+  consuming gate's (grounding-mcp) own documentation, not restated here.
+  The keyed-marker grammar sentence is now a single generalised rule: write
+  the marker exactly in its documented form, on its own line; a deviating
+  line is either rejected, which blocks the run, or not recognised at all
+  (for example inside a list bullet), which leaves the binding for that
+  repository silently missing. The consumer detail that a real key left
+  with the placeholder value `<sha>` is read as-is and blocked by the
+  verdict layer lives in `docs/okf/run-state-lifecycle-and-markers.md`,
+  not in the skill text. `test/docs-consistency.test.ts`'s pointer-doc
+  describe block now routes six of its eight checks through one shared
+  `expectPointerMention` helper that asserts the exact phrase `` `.ai/run`
+  pointer `` (a bare `.ai/runs/` mention alone cannot satisfy it); the
+  SKILL.md Run state contract check and the exact-keyed-example check keep
+  their own specific phrases instead, and a further check pins the
+  grammar rule's wording ("on its own line", both deviation outcomes).
+  `test/template-markers.test.ts`'s property test now carries
+  grounding-mcp's `KEYED_RUN_BASE_STRICT` and `PLACEHOLDER_KEY` regexes
+  verbatim, kept in sync by hand, instead of a locally tightened mirror,
+  and still asserts that two constructed near-miss variants (uppercase,
+  space before the colon) do not match. `agents-md-section.md`'s
+  run-directory bullet still notes the run directory can live "in the
+  workspace or a touched repository". `docs/okf/run-state-lifecycle-and-markers.md`
+  carries the corrected claims plus the consumer's own test-measured
+  evidence for the scan fallback and the malformed/not-seen split, and
+  every `docs/okf/*.md` anchor that cited a line range shifted by either
+  round's edits was re-pointed in the same PR.
+- An operator-level install layer: a new `operator-manifest.ts` module and
+  an operator home directory (default `~/.orchestrator-workflow/`,
+  overridable via the `ORCHESTRATOR_WORKFLOW_HOME` environment variable)
+  hold one manifest per operator (`{ kit, schemaVersion: 1, defaults: {
+  harnesses, profile, tiers, models }, targets: [{ path,
+  lastAppliedVersion, lastAppliedAt }], createdAt, updatedAt }`), separate
+  from each repository's own `.ai/workflow/manifest.json`. Four new
+  subcommands sit alongside the existing per-repository `init`/`uninstall`,
+  which stay fully supported and unchanged: `setup` writes or updates the
+  operator defaults without touching any repository; `apply --target
+  <repo>` projects those defaults, and the target's own previously
+  recorded settings, onto one repository through the same
+  option-resolution logic `init` uses (`resolveInitInputs`, extracted for
+  reuse), and registers the target, by its resolved real path, in the
+  operator manifest, with `--sync` inverting precedence so the operator's
+  defaults win over the target's recorded profile/tiers/models, and
+  `--pin`/`--unpin`/`--force-pin` controlling the new per-repo kit-version
+  pin (below); `doctor [--json] [--prune]` walks the registry and reports
+  each target's status (`clean`, `divergent`, `version-lag`, `drift`,
+  `missing`, `no-manifest`, `unverifiable`), exiting `2` when the operator
+  manifest is missing or unreadable (or, with `--prune`, when the manifest
+  lock cannot be acquired or the rewrite fails), `1` when any target is
+  `drift`/`missing`/`no-manifest`/`unverifiable`, else `0`, and `--prune`
+  removes `missing`/`no-manifest` targets (never `unverifiable`) and
+  rewrites the manifest in normalized form; `adopt [dir] [--json]` registers an
+  already-installed repository verbatim, touching nothing in it,
+  bootstrapping the operator manifest from the repository's own recorded
+  settings when none exists, recording the repository's own version as
+  `lastAppliedVersion`, and printing that target's `doctor` report (exit
+  `1` only on drift, exit `2` for a precondition failure). Design
+  decisions: no new binary, all four subcommands live on the existing
+  `orchestrator-workflow` CLI; the registry is implicit, `apply`/`adopt`
+  register as a side effect of a real run and `doctor --prune` is the only
+  way to remove an entry; a multi-repo workspace root is an ordinary
+  target, nothing special. `README.md` gained a new "Operator-level
+  install" section and `INSTALL-AGENT.md` gained the operator path (an
+  installing agent runs `apply` instead of `init` when an operator
+  manifest already exists, and `adopt` for an already-installed
+  repository) plus the new operator-home and `pin` entries in its Write
+  surface list. Consumer-side evidence: agent-tasks `b457ee55`, PRs
+  #142-#147.
+- The repo manifest (`.ai/workflow/manifest.json`) gained one optional
+  field, `pin`: a kit-version string. `apply --pin <version>` sets or
+  replaces it (trimmed; empty, whitespace-only, or containing internal
+  whitespace rejected as a usage error, exit `2`, writing nothing),
+  `--unpin` clears it, and `--force-pin` advances an existing pin to the
+  running version (a no-op on an unpinned target); read by `apply`'s pin
+  gate and by `doctor`, which on a pinned target compares the pin against
+  the installed version instead of the installed version against the
+  running kit. Purely additive: a
+  caller that never sets it sees a byte-identical manifest to before.
+- `init --harness none` (the literal word `none`, alone): a templates-only
+  mode that writes only `.ai/workflow/**` and `.ai/runs/.gitkeep`, records
+  `harnesses: []` in the manifest, and touches no `AGENTS.md`, `CLAUDE.md`,
+  or per-harness directory. `none` combined with a real harness name
+  (`none,claude`, either order) is a usage error rather than an implicit
+  precedence rule. A plain re-run (no `--harness` flag) after a recorded
+  `harnesses: []` install stays templates-only instead of falling back to
+  filesystem detection; a later `init --harness <list>` on the same target
+  adds harness files and manifest entries additively, without touching the
+  already-installed templates. `apply` shares the same option parsing (an
+  explicit `--harness none` on an `apply` call resolves to templates-only
+  too) but not the re-run stickiness: `apply`'s own harness fallback chain
+  (target's recorded harnesses, else the operator defaults, else detection)
+  is unchanged, so a target `apply`-installed as templates-only is not
+  guaranteed to stay that way on a flagless `apply` re-run, a gap left open
+  by this change rather than closed. The closing summary line prints
+  `templates only` instead of `installed for: ` followed by nothing.
+  Motivated by friction filed 2026-08-28 while refreshing an agent-tasks
+  install that had ended up in the templates-only manifest shape (`harnesses:
+  []`, produced by a 0.14.0-era install with no harness configured) with no
+  supported way to reproduce or re-render that state: `--harness none`
+  rejected the literal value, and `--harness ""` fell back to detection,
+  which under `--yes` installed `claude` unasked. Documented in `README.md`
+  ("Non-interactive") and `docs/okf/install-fence-mechanics.md` (new
+  "`--harness none` (templates-only mode)" section). Agent-tasks 613316c9.
+
+### Changed
+
+- `setup`, `apply`'s registration step, `doctor --prune`, and `adopt` all
+  write the operator manifest through the same locked write API,
+  `updateOperatorManifest`/`withOperatorManifestLock`, backed by one
+  advisory lock (`.manifest.lock` in the operator home, stale after 30s)
+  so concurrent `orchestrator-workflow` invocations on one machine cannot
+  race each other's writes.
+
+## [0.25.0] - 2026-08-27
+
+### Added
+
+- A "Review-round escalation budget" (`SKILL.md`, new section right after
+  the existing Round-2 halt rule): by the second round-2 halt signal on a
+  task, or its third `fix_required` review round, whichever comes first,
+  the orchestrator now picks one of three escalations, tier/model
+  escalation, an advisor spawn, or an operator merge-hold, instead of
+  running another round unaided, and records the choice in
+  `03-decisions.md`'s new Review-round escalation section (the
+  `review-round-escalation` marker: `n/a | tier_escalation | advisor |
+  merge_hold`, `n/a` a deliberately fail-open default since most runs
+  never trigger the budget at all, unlike the `TODO` fail-closed sentinel
+  the `solution-acceptance:` marker family uses). Which of the three is
+  picked stays a judgment call; only that one is picked and recorded is
+  now mandatory, and escalating never substitutes for a review round.
+  `agents-md-section.md` carries the same rule in short form. The
+  reviewer output contract (`SKILL.md` and `reviewer.md`) gained a
+  `recurrence: new | repeated` field per finding, and step 7 now has the
+  orchestrator name the review round number in the briefing when it is
+  not the task's first, so the reviewer can classify each finding against
+  the rounds it was told about instead of the orchestrator re-deriving
+  recurrence by hand. `03-decisions.md`'s new marker is a documented
+  convention only: nothing in this package's own code reads it today
+  (unlike the `solution-acceptance:` markers, which grounding-mcp's
+  run-completeness reader does parse); wiring it into that reader, if
+  wanted, is a follow-up in the consuming project, not part of this
+  change.
+
+  Evidence: agent-tasks d03af8f6 (pandora run
+  `.ai/runs/2026-08-26-open-pool-batch30`, a harness risk-gate deletion
+  arm) ran five implementer rounds on the same effort tier (rounds 1-5, the
+  default-tier implementer, Sonnet) before this rule existed; each reviewer
+  round found one new HIGH on the permissive side of the same detection layer
+  (first-segment matching, wrapper flags, xargs flags, a find-root premise
+  twice, xargs `-i`/append), and the Round-2 halt rule's split-or-redesign
+  response was applied three times (D-014, D-019, D-022/D-023) without ever
+  escalating tier, model, or to the advisor, and without a merge-hold. Only
+  after round 5 did the operator suggest a stronger model (D-024); round 6, on
+  Fable with the `-xhigh` variant, found and closed twelve further fail-open
+  classes in one round by its own 248-probe audit, and the following review
+  found only one remaining, a documentation-only medium. A same-run comparison
+  task, agent-tasks da823721, needed three rounds with one round-2 halt and
+  was accepted after it, well inside this budget. This is the first data
+  point relating implementer model strength to round count on a
+  permissive-security-parser class of task; the 2026-08-24 tier A/B (see
+  `[0.23.0]` below) measured only
+  `implementer-low` against the default tier on a different task shape,
+  not model strength, so whether a stronger model generally shortens
+  these rounds remains open.
+- A new `okf-anchor-guard` job in `.github/workflows/ci.yml` (this repo)
+  runs okf-kit's anchor check against `docs/okf` and fails the build (no
+  branch-protection change; master has no required checks today) when an
+  edit to `SKILL.md`, an agent template under `assets/agents/`,
+  `src/models.ts`, a `test/*.test.ts` file, any other `src/*.ts` module,
+  a run template under `assets/templates/`, or `assets/agents-md-section.md`
+  shifts a cited range out of the section or text an anchored bundle
+  citation names, instead of only the existing warn-only `okf-staleness.yml`
+  drift watch (which never blocks by design and stays untouched). Every
+  in-scope bundle citation into those source categories now carries a
+  string-form anchor (up from a first-round draft that review round 2
+  found had missed 44 bare, non-backtick-delimited citations in two of the
+  five docs/okf siblings; the citation parser was corrected to match
+  okf-kit's own backtick-optional shape; scope later widened from the
+  original four categories to every `src/*.ts` module and every
+  `assets/templates/*.md` plus `assets/agents-md-section.md`, agent-tasks
+  ca9d5048); the `CHANGELOG.md` citations still carry heading anchors from
+  the prior round (that mechanism is untouched, but every CHANGELOG entry
+  added above them, this one included, re-points all of them -- see
+  `docs/okf/log.md` for the live count and the re-point history, not
+  hand-copied here since it drifts with every CHANGELOG edit).
+- Every anchor now satisfies two mechanically-checked properties review
+  round 2 added (a first-round anchor sitting on a wide range's first line,
+  as 107 of 121 did, survives an insertion shorter than the range itself --
+  measured: round 1 had 46 SKILL.md-targeting anchors, and a 1-line
+  insertion near the top of SKILL.md left 24 of them silently green): (a)
+  the anchor text occurs on the LAST line of its cited range (ranges were
+  narrowed where needed to end on real content rather than a
+  blank/closing-brace line), and (b) it occurs at most 3 times in the
+  whole target file (23 first-round anchors used a too-common token, e.g.
+  `describe(`, and were
+  replaced). Two anchors were additionally re-pointed because the text
+  they carried did not match the claim their citing sentence made, not
+  just its mechanical position; see `docs/okf/log.md` for both. Pinned by
+  three new tests in `test/docs-consistency.test.ts` (version-pin
+  coverage extended to every `.github/workflows/*.yml` file, not just
+  `okf-staleness.yml`; the last-line/occurrence-cap rule, verified red
+  against the first-round anchors and green against this round's; and an
+  erosion brake asserting zero unanchored in-scope citations going
+  forward). `ci.yml`'s anchor-finding jq filter now matches any
+  `anchor-*`-tagged finding by pattern instead of four hardcoded rule
+  ids, guarded by a new self-test step that builds a throwaway fixture
+  bundle with one deliberately drifted anchored citation and requires the
+  filter to catch it before the real check runs.
+  `okf-kit check` reports the same 0 errors / 13 warnings / 22 notices
+  before and after this round's full anchor rewrite (0 anchor findings
+  either way; the 13 pre-existing warnings are unrelated
+  `install-fence-mechanics.md` short-form findings against `init.test.ts`
+  and `init.ts`). Differential mutation probe, replacing the first
+  round's single 27-finding number: inserting `k` dummy lines near the
+  top of SKILL.md, 52/52 (100%) of its unique cited ranges now produce a
+  finding at `k=1`; 51/52 (98%) at `k=2`, one named exception (a
+  same-block token collision, see `docs/okf/log.md`). A `package.json`
+  patch-version bump still leaves the anchor-finding count at 0,
+  confirming no false positive. Residual gaps named in `docs/okf/log.md`:
+  a content change inside a cited range that neither shifts its line
+  count nor disturbs the anchor text stays invisible to this check
+  (mechanical, never semantic, the same limit okf-kit's own README
+  documents), plus the one named same-block token collision above
+  (agent-tasks task 578f5bfd, review round 2; following the
+  anchored-citations feature itself, task 5c8013c0, and its release, task
+  c0effc67).
+
+### Changed
+
+- `docs/okf/subagent-contracts-superset.md`: rewrote its 22 sibling short-
+  form citations (21 initially, plus one missed and fixed this round) from
+  the parenthesized form (`(N-M)`) to the colon form (`, :N-M`) so
+  `citations-resolve` checks them again. Neither form was ever machine-
+  checked in a released `okf-kit`: the colon-form gate and the drop of
+  paren-form collection landed in the same `[Unreleased]` entry, so
+  "dropped" overstates it. Inserting this entry shifts every later line
+  number in this file, so any absolute-line `CHANGELOG.md` citation below
+  it breaks until re-pointed; this round re-points all sixteen such
+  citations across the three touched docs/okf siblings
+  (`subagent-contracts-superset.md`, `review-gate-and-waivers.md`,
+  `run-state-lifecycle-and-markers.md`), each checked against the
+  `## [x.y.z]` section its own sentence names, not against a byte-diff of a
+  moving base. `okf-kit check` against a repo build (not the published
+  package) reports 0 errors / 13 warnings / 22 notices; all 13 are
+  pre-existing `install-fence-mechanics.md` short-form findings unrelated
+  to this change, so the three touched docs carry no citations-resolve or
+  sources-fresh finding of their own (log.md records the fuller
+  sources-fresh investigation, since that count depends on this round's
+  commit shape, not on the citations themselves). Coverage holds only
+  against a repo build: CI's `okf-staleness.yml` still pins the published
+  `okf-kit@0.5.0`, which predates short-form colon resolution, so it
+  reports 0 short-form findings until that release ships (agent-tasks task
+  2e3e5f4b).
+- All sixteen `CHANGELOG.md` citations across the three `docs/okf` siblings
+  above now also carry a heading anchor (`` `CHANGELOG.md:N-M#x.y.z` ``, a
+  new `citations-resolve` form -- see okf-kit's own CHANGELOG for the
+  design), pinning each one to the release section its own sentence names
+  instead of only to a line range that a future top-of-file insertion can
+  silently shift into the wrong section. `okf-kit check` against a repo
+  build still reports the same 0 errors / 13 warnings / 22 notices as
+  above (all pre-existing, unrelated to this change); a mutation probe that
+  moved one migrated citation's range into its neighbouring release
+  section, and a second probe that inserted a dummy entry at the top of
+  this file (shifting every citation below it), were both caught by the
+  new anchor check and reverted (agent-tasks task 5c8013c0).
+
+### Corrections
+
+- Correction to the "Known limit of the pack" note in the 0.24.0 entry
+  below: this is not an `orchestrator-workflow` behavior change, it
+  documents a `slop-detector` fix. The 0.24.0 note described a known limit
+  of `placement-slop`, that an `allow` match suppressed every placement
+  rule on the line it matched, not just the marker span it was meant to
+  excuse. `slop-detector` has since fixed this (`placement.allow` is now
+  span-scoped, not line-wide). Consumer-visible effect: a config that
+  reported clean before can now report a `block`-severity finding (e.g.
+  `placement-slop/home-path`) when a home path, a date, or a tally phrase
+  shares a line with an allowed marker.
+
 ## [0.24.0] - 2026-08-24
 
 ### Changed

package/INSTALL-AGENT.md

@@ -31,10 +31,23 @@ which is mutable. For a stable audit, pin the URL to a commit SHA instead
 3. **Run the non-interactive installer** with your answers:
    `npx orchestrator-workflow init --yes --harness ... --profile ... --models ... [--tiers]`.
    If the installer reports conflicts with locally edited files, the agent
-   shows them to you and asks before any `--force` re-run.
+   shows them to you and asks before any `--force` re-run. **The operator
+   path**: when an operator has already run `orchestrator-workflow setup`
+   on this machine (an operator manifest exists at
+   `<operator home>/manifest.json`, where the operator home is
+   `~/.orchestrator-workflow/` unless `ORCHESTRATOR_WORKFLOW_HOME` names a
+   different directory), the agent runs
+   `orchestrator-workflow apply --target <repo>` instead of `init`, which
+   sources its defaults from that operator install and registers the
+   repository under it. A repository that already has the kit installed
+   and only needs bringing under that management, with nothing in it
+   changed, is registered with `orchestrator-workflow adopt <repo>`
+   instead of either command.
 4. **Manual fallback only when npx or the registry is unavailable**: create
    the same files by hand from this repository's `assets/` directory,
-   following the byte-precise rules in step 4 below.
+   following the byte-precise rules in step 4 below. This manual path
+   covers `init` only; there is no manual equivalent for `apply` or
+   `adopt`, both of which require the installed CLI.
 5. **Report back**: which harnesses were installed, which profile and model
    each role uses, whether effort-tier variants were rendered, and any
    conflicts left in place.
@@ -44,7 +57,18 @@ which is mutable. For a stable audit, pin the URL to a commit SHA instead
 The install creates or touches only these paths:
 
 - `.ai/workflow/templates/00-goal.md` through `06-handoff.md`,
-  `.ai/workflow/manifest.json`, `.ai/runs/.gitkeep` (new files)
+  `.ai/workflow/manifest.json`, `.ai/runs/.gitkeep` (new files). The
+  orchestrator later writes a per-worktree `.ai/run` pointer at run time (a
+  machine-local absolute path, not written by the installer); add it to the
+  repository's `.gitignore`. This repository's own `.ai/workflow/manifest.json`
+  can additionally carry one optional field, `pin`: a kit version recorded
+  by `apply --pin`/`--unpin`/`--force-pin`, absent when no pin was ever set.
+- **Operator path only** (`apply`/`adopt`, not `init`): the operator's own
+  home's manifest, `<operator home>/manifest.json`, where the operator home
+  is `~/.orchestrator-workflow/` unless `ORCHESTRATOR_WORKFLOW_HOME` names a
+  different directory, gains or updates its record of this repository,
+  guarded by a transient `.manifest.lock` directory held only for the
+  duration of that write. Neither path lives inside the target repository.
 - `AGENTS.md`: the marker-fenced workflow section is appended (file created
   when missing); content outside the
   `<!-- orchestrator-workflow:begin -->` / `<!-- orchestrator-workflow:end -->`
@@ -126,6 +150,19 @@ steps in the repository you were asked to install into.
    on a re-run. If the command reports conflicts, show them to the operator
    and ask before re-running with --force.
 
+   **Operator path**: before running `init`, check whether an operator
+   manifest already exists on this machine, at
+   `<operator home>/manifest.json` (the operator home is
+   `~/.orchestrator-workflow/` unless `ORCHESTRATOR_WORKFLOW_HOME` names a
+   different directory). If it does, run
+   `orchestrator-workflow apply --target <repo>` with the same flags in
+   place of `init --yes` instead: it sources its defaults from the operator
+   install and the target's own prior settings, and registers the
+   repository. If the repository already has the kit installed and the
+   operator only wants it brought under that management without any file
+   changes, run `orchestrator-workflow adopt <repo>` instead and skip the
+   rest of this step.
+
 4. Only if npx or the registry is unavailable, scaffold manually from
    https://github.com/LanNguyenSi/agent-dx/tree/master/packages/orchestrator-workflow/assets.
    This manual path does not cover `--tiers`: it never renders
@@ -135,7 +172,10 @@ steps in the repository you were asked to install into.
 
    - `.ai/workflow/templates/00-goal.md` through `06-handoff.md` from
      `assets/templates/`, unchanged.
-   - `.ai/runs/.gitkeep`, empty.
+   - `.ai/runs/.gitkeep`, empty. The orchestrator later writes a
+     per-worktree `.ai/run` pointer at run time (a machine-local absolute
+     path, not written by the installer); add it to the repository's
+     `.gitignore`.
    - Append the content of `assets/agents-md-section.md` to `AGENTS.md`
      (create the file when missing; the installer starts a fresh file with a
      `# Agent instructions` heading). Never change anything outside the

package/README.md

@@ -73,6 +73,26 @@ npx orchestrator-workflow init --harness claude,codex,opencode --models "impleme
 npx orchestrator-workflow init --profile minimal --yes
 ```
 
+**Templates-only mode.** `--harness none` (the literal word `none`, on its
+own) installs only `.ai/workflow/**` and `.ai/runs/.gitkeep`: no
+`AGENTS.md`, no `CLAUDE.md`, no harness-specific directory, and a manifest
+recording `harnesses: []`. Use it for a repo that wants the run-state
+templates and the workflow itself, but no per-harness subagent files yet
+(e.g. no harness has been chosen, or the files were dropped by hand).
+`none` combined with a real harness name (`--harness none,claude`) is
+rejected as ambiguous rather than silently picking one. A plain
+**non-interactive** re-run (no `--harness` flag) after a templates-only
+install stays templates-only; add a harness back with an explicit
+`--harness <list>` on a later run, the same explicit-flag-wins rule
+`--profile`/`--models`/`--tiers` use, applied to the no-harness case. An
+**interactive** re-run is different: it still prompts, with nothing forced
+pre-selected, instead of silently skipping straight back to templates-only
+without asking; deselect every checkbox to stay templates-only.
+
+```bash
+npx orchestrator-workflow init --harness none --yes
+```
+
 To let a coding agent do the install, give it this single line:
 
 ```text
@@ -97,6 +117,10 @@ to a commit SHA for a stable audit.
 AGENTS.md             marker-fenced "Agentic Coding Workflow" policy section
 ```
 
+The orchestrator writes a `.ai/run` pointer file in every worktree a run
+touches (a machine-local absolute path, not written by the installer); add
+it to the repository's `.gitignore`.
+
 Per selected harness:
 
 | Harness | Files | Notes |
@@ -329,14 +353,107 @@ effort actually taking effect.
 The pin is also emitted unconditionally regardless of which model the role
 resolves to via `--models`, including a model with no effort support at all
 (e.g. `--models reviewer=haiku` still renders `model: haiku` followed by
-`effort: high`). A wire probe on 2026-08-19 (not re-measured for this doc)
-showed the Claude Code CLI silently drops the `effort:` parameter for Haiku
-4.5 rather than rejecting it: the value is ignored, not an install-time or
-run-time error.
+`effort: high`). On Haiku 4.5, which does not support the `effort`
+parameter, the harness ignores the pinned value rather than rejecting it
+(anchored by a measurement, see CHANGELOG 0.23.0).
+
+## Operator-level install
+
+Alongside `init`, which installs the kit into one repository from that
+repository's own working directory, an operator who maintains many
+repositories can set defaults once and project them onto each target
+instead of re-answering the same prompts per repo. This layer adds no new
+binary: `setup`, `apply`, `doctor`, and `adopt` below are subcommands of the
+same `orchestrator-workflow` CLI `init` and `uninstall` already ship as, and
+`init`/`uninstall` remain fully supported and unchanged for a
+single-repository install.
+
+```bash
+orchestrator-workflow setup --yes
+orchestrator-workflow apply --target /path/to/repo
+```
+
+**`setup`** writes or updates this operator's default install options
+(harnesses, profile, models, tiers) as the baseline for future installs; it
+touches no repository. A flag always wins; a flag-less re-run keeps the
+previously stored values; a first-ever `setup` falls back to `claude` /
+`full` / the kit's default models / tiers off. `setup` takes the same
+option flags as `init` (`--harness`, `--profile`, `--models`, `--tiers` /
+`--no-tiers`, `--opencode-provider`, `--yes`). The defaults live in
+`<operator home>/manifest.json`, where the operator home is
+`~/.orchestrator-workflow/` unless the `ORCHESTRATOR_WORKFLOW_HOME`
+environment variable names a different directory.
+
+**`apply --target <repo>`** projects the operator's install onto a target
+repository and registers that target, by its real resolved path, in the
+operator manifest. It requires a prior `orchestrator-workflow setup`;
+without one it exits `1` with "No operator setup found". Option resolution
+follows one precedence order: an
+explicit flag wins, then the target's own previously recorded settings,
+then the operator's defaults (harnesses fall back one step further, to
+what `init` would have auto-detected). Pass `--sync` to invert that for
+profile, tiers, and models: the operator's defaults then win over whatever
+the target already had recorded. A target pinned to a kit version other
+than the one being applied is skipped rather than touched (see the pin
+rule below). `apply` also takes the same install options as `init` (`--harness`,
+`--profile`, `--models`, `--tiers` / `--no-tiers`, `--opencode-provider`,
+`--force`, `--yes`), which feed the precedence rule above.
+
+**`doctor [--json] [--prune]`** reports every operator-registered target's
+status: `clean`, `divergent` (from the operator defaults), `version-lag`,
+`drift` (installed files edited, deleted, or unreadable since install),
+`missing`, `no-manifest`, or `unverifiable`. It exits `2` when the operator
+manifest is missing or unreadable, or, with `--prune`, when the operator
+manifest lock cannot be acquired or the rewrite fails; `1` when any target
+is `drift`, `missing`, `no-manifest`, or `unverifiable`; and `0` otherwise.
+`--json` prints one JSON object instead
+of human output, with one entry per target plus the operator home and
+version. `--prune` removes `missing` and `no-manifest` targets from the
+registry before reporting (never an `unverifiable` one, since that status
+means the check itself was inconclusive, not that the target is confirmed
+gone) and rewrites the manifest file in its normalized form.
+
+**`adopt [dir] [--json]`** brings a repository that already has the kit installed,
+by hand or by an earlier `init`, under the operator's management without
+changing anything in that repository: it registers the repository
+verbatim, using the repository's own recorded settings to bootstrap the
+operator manifest when none exists yet, records the repository's own
+installed version as its baseline, and prints that one target's `doctor`
+report. It exits `1` only when the freshly adopted target itself reports
+drift, and `2` for a precondition failure (no repo manifest, an unreadable
+or foreign manifest, or a lock or write failure).
+
+**The kit-version pin.** A repository's own manifest can additionally
+carry an optional `pin`: a kit version that `apply` must match before it
+will touch that repository again. `apply` skips (exit `0`) a target pinned
+to a different version than the one being applied. `--pin <version>` sets
+or replaces the pin and applies regardless of any existing one; `--unpin`
+clears it and applies; `--force-pin` advances an existing pin that
+differs, but has no effect on a target with no pin recorded (it stays
+unpinned). `doctor` reports `version-lag` when the installed version
+differs from the running kit version; on a pinned target the pin is
+compared against the installed version instead, so a pin equal to the
+installed version is `clean` and a pin that no longer matches it is
+`version-lag`.
+
+**The registry is implicit**, not a separate command: `apply` and `adopt`
+register a target as a side effect of a real run, and `doctor --prune` is
+how a registry entry is removed again; there is no bare register or
+unregister command. The workspace root of a multi-repo checkout is treated
+as an ordinary target, nothing special.
+
+All writes to the operator manifest, by `setup`, `apply`, `doctor --prune`,
+and `adopt` alike, go through one advisory lock in the operator home, so
+concurrent orchestrator-workflow commands on the same machine cannot
+corrupt each other's state.
 
 ## Ownership and re-runs
 
-`init` is idempotent: a second run changes nothing. The rules:
+`init` is idempotent: a second run changes nothing. `apply` installs
+through that same `runInit` path and is subject to the same
+conflict/`--force`/ownership rules; on the repository side it changes
+nothing either, but it refreshes this target's entry in the operator
+manifest on every run. The rules:
 
 - `AGENTS.md` and `CLAUDE.md` belong to you. The installer only appends its
   fenced section or the import line, and on re-run replaces only the content
@@ -347,9 +464,9 @@ run-time error.
   updates files you never touched and reports files you edited as conflicts
   instead of overwriting them; `--force` overwrites those too.
 - `.ai/workflow/manifest.json` is the kit's state file. It records the applied
-  version, harnesses, role profile, models, the `--tiers` flag, and file
-  hashes, and is rewritten whenever that state changes; do not edit it by
-  hand.
+  version, harnesses, role profile, models, the `--tiers` flag, the optional
+  kit-version pin, and file hashes, and is rewritten whenever that state
+  changes; do not edit it by hand.
 
 ## Uninstall
 

package/assets/agents/reviewer.md

@@ -26,6 +26,11 @@ Check, at minimum:
   reusable instruction file (a skill, an agent prompt, an AGENTS.md section, a
   template)? Report it; the fix is to move the evidence to the changelog, the
   run files, or the consuming workspace and leave a one-line pointer.
+- Recurrence: when the briefing tells you this is not the task's first
+  review round, classify each finding as `new` or `repeated` against the
+  earlier rounds you were told about; on a first round every finding is
+  `new` by definition. The orchestrator uses this to detect the
+  review-round escalation budget's trigger.
 
 Rules:
 
@@ -73,6 +78,7 @@ findings:
     category: correctness | architecture | security | tests | maintainability | performance | docs
     description: ""
     suggested_fix: ""
+    recurrence: new | repeated
 acceptance_recommendation: accept | accept_with_notes | fix_required | reject
 missing_tests:
   - ""

package/assets/agents-md-section.md

@@ -103,6 +103,21 @@ trivial change.
   the Accepted Waivers section of `06-handoff.md`.
 - Medium and low findings are addressed or consciously accepted at the
   orchestrator's judgment.
+- Review-round escalation budget: by the second round-2 halt signal on a
+  task, or its third `fix_required` review round, whichever comes first,
+  the orchestrator picks one of tier/model escalation (raise the
+  implementer to at least `-xhigh` where installed, or to the strongest
+  model available, until that is exhausted), an advisor spawn (where the
+  advisor is installed, `full` profile only; under a `minimal` profile
+  the exhausted tier path falls straight to the merge-hold), or an
+  operator merge-hold, and adds a row (task, choice, reason) to
+  `03-decisions.md`'s Review-round escalation table, then sets the
+  `review-round-escalation` marker to the most recent choice. A counted
+  round is a completed reviewer return recommending `fix_required` or
+  `reject`; a misfired review is not a round. Which of the three is
+  picked is judgment; that one is picked and recorded is not. Escalating
+  never substitutes for a review round and comes in addition to the halt
+  rule's split-or-redesign response, not instead of it.
 
 ### Instruction trust boundary
 
@@ -135,11 +150,15 @@ Workflow state lives under `.ai/`:
 
 - `.ai/workflow/templates/` holds the canonical file templates
   (`00-goal.md` through `06-handoff.md`).
-- Each unit of work gets a run directory `.ai/runs/YYYY-MM-DD-<slug>/`,
-  created by copying the templates. The newest run directory is the active
-  one; older ones are the auditable history.
+- Each unit of work gets a run directory `.ai/runs/YYYY-MM-DD-<slug>/` (in
+  the workspace or a touched repository), created by copying the templates.
+  The newest run directory is the active one; older ones are the auditable
+  history.
 - `.ai/workflow/manifest.json` records the installed kit version, the chosen
   harnesses, and the per-role model preferences.
+- Every worktree a run touches carries a `.ai/run` pointer (absolute path of
+  the run directory, gitignored) and `00-goal.md` carries one
+  `run-base[<repo-basename>]` marker per repository for multi-repo runs.
 
 ### Models