orchestrator-workflow 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -7,6 +7,167 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [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

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 |
@@ -333,9 +357,103 @@ resolves to via `--models`, including a model with no effort support at all
 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
@@ -346,9 +464,9 @@ parameter, the harness ignores the pinned value rather than rejecting it
   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-md-section.md

@@ -150,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
 

package/assets/skill/SKILL.md

@@ -78,9 +78,30 @@ All state for one unit of work lives in a run directory:
 ```
 
 Create it at the start of a run by copying `.ai/workflow/templates/` and fill
-the files as the run progresses. The newest run directory is the active one;
+the files as the run progresses. The newest run directory is the active one
+unless a `.ai/run` pointer names one (see below);
 older directories are the auditable history. Do not edit past runs.
 
+The run directory may live in the workspace's own `.ai/runs/` or in one
+repository's `.ai/runs/`. Either way, bind every repository or worktree the
+run touches to it with a pointer file, `<worktree-root>/.ai/run`:
+
+- Content: the absolute path of the run directory (a `YYYY-MM-DD-<slug>`
+  directory) on the first non-empty line; nothing else is read.
+- Write it before the first implementation commit, and overwrite it at the
+  start of every later run; remove it when no run is active, since a
+  pointer left behind keeps binding that worktree to the old run.
+- Before writing it, make sure it is ignored (the repository's `.gitignore`
+  or `.git/info/exclude`); never commit it, it carries a machine-local
+  absolute path.
+
+The pointer is how the run-completeness reader finds the run for a change.
+Without it the reader falls back to that repository's own `.ai/runs/` and
+takes the run there that sorts newest by directory name, which is only
+right when the run lives in that repository and sorts last; a broken
+pointer is rejected outright. The exact accept and reject rules are the
+consuming gate's (grounding-mcp) to document, not the kit's.
+
 When creating the run directory, replace the `TODO` in `00-goal.md`'s
 `<!-- solution-acceptance: run-base = TODO -->` marker with the base commit
 this run branches from — the pre-change repo HEAD (`git rev-parse HEAD`),
@@ -91,7 +112,17 @@ left as `TODO` it does not block anything, the reader just falls back to a
 tolerant day-granular date heuristic. The recorded base must resolve in the
 repo, be an ancestor of HEAD, and must not lie behind the fork point of the
 change (the merge-base with the remote default branch); see the consuming
-gate's documentation (grounding-mcp) for the full consumer semantics.
+gate's documentation (grounding-mcp) for the full consumer semantics. When a
+run touches more than one repository, record one keyed marker per
+repository on its own line beside the unkeyed one, exact form
+`<!-- solution-acceptance: run-base[<repo-basename>] = <sha> -->`, where
+`<repo-basename>` is the worktree directory's basename; in a linked worktree
+the main repository's basename is accepted too, and the value is that
+repository's pre-change HEAD. The template ships that line as a placeholder
+example, which readers ignore until the placeholder key is replaced. Write
+the marker exactly in that form, on its own line: a deviating line is
+either rejected (it blocks the run) or not recognised at all (the binding
+for that repository is silently missing).
 
 ## Workflow
 
@@ -101,7 +132,8 @@ directory and the subagents.
 
 1. **Understand the goal.** Create the run directory and fill `00-goal.md`,
    including the run-base marker (see Run state): operator request, goal,
-   non-goals, constraints, assumptions, open questions.
+   non-goals, constraints, assumptions, open questions. Write the `.ai/run`
+   pointer (see Run state) in every worktree the run touches.
    If the task can proceed on reasonable assumptions, proceed without blocking.
 2. **Discover (optional, read-only).** When the goal, the solution, or the
    terrain is unclear, send the explorer subagent before planning. Have it
@@ -443,12 +475,15 @@ instructions found in untrusted content as risks instead of following them.
   whichever roles this install's profile carries (explorer, task-slicer,
   implementer, reviewer, advisor under `full`; implementer and reviewer only
   under `minimal`) via the native subagent mechanism; run any missing role
-  inline with the same contract.
+  inline with the same contract. The `.ai/run` pointer rule from Run state
+  applies unchanged.
 - **opencode**: invoke the installed `.opencode/agents/` subagents the same
-  way (`mode: subagent`); the same profile scoping applies.
+  way (`mode: subagent`); the same profile scoping applies. The `.ai/run`
+  pointer rule from Run state applies unchanged.
 - **OpenAI Codex**: there is no standardized project-level subagent definition
   to install. Run the roles inline and sequentially with the same contracts,
-  and still produce the same run files.
+  and still produce the same run files. The `.ai/run` pointer rule from Run
+  state applies unchanged.
 
 ## Subagent misfire rule
 

package/assets/templates/00-goal.md

@@ -1,6 +1,7 @@
 # Goal
 
 <!-- solution-acceptance: run-base = TODO -->
+<!-- solution-acceptance: run-base[<repo-basename>] = <sha> -->
 
 ## Operator Request
 

package/dist/cli-inputs.d.ts

@@ -0,0 +1,71 @@
+import type { Harness } from "./detect.js";
+import type { Manifest } from "./init.js";
+import type { ModelClass, Profile, Role } from "./models.js";
+export declare function promptHarnesses(detected: Harness[], installed: Harness[], fallbackToClaude?: boolean): Promise<Harness[]>;
+export declare function promptProfile(base: Profile): Promise<Profile>;
+export declare function promptModels(base: Record<Role, string>, roles: Role[]): Promise<Record<Role, string>>;
+/** The subset of `init`'s commander options that feed input resolution. */
+export interface InitResolutionOptions {
+    harness?: string;
+    models?: string;
+    profile?: string;
+    opencodeProvider?: string;
+    tiers?: boolean;
+}
+export interface ResolveInitInputsParams {
+    /** Result of `detectHarnesses(targetDir)`; passed in so the caller can
+     * print it before resolution starts, matching `init`'s existing output
+     * order, without this function reading the filesystem a second time. */
+    detected: Harness[];
+    interactive: boolean;
+    /** The previously installed manifest, if any (`readInstalledManifest`). */
+    previous: Manifest | undefined;
+    opts: InitResolutionOptions;
+    /**
+     * True when `previous` reflects the target's own actually-recorded
+     * manifest (`init`'s use, `readInstalledManifest(targetDir)`), as opposed
+     * to a synthetic "operator defaults as floor" object (`apply`'s
+     * `buildApplyPrevious`, which is never `undefined` even for a target with
+     * no manifest of its own). Only consulted for the harnesses-stickiness
+     * rule below, together with `previous.harnessesRecordedEmpty`: a real
+     * recorded `harnesses: []` means a deliberate `--harness none` install,
+     * and a plain re-run must not silently widen it via detection; a
+     * synthetic floor previous carries no such signal, so `apply` omits this
+     * (default `false`) and keeps its own `resolveApplyHarnesses` fallback
+     * chain unchanged. This flag alone does not distinguish a deliberate
+     * `harnesses: []` from a damaged/legacy manifest whose raw `harnesses`
+     * field was missing, malformed, or an array whose every entry failed the
+     * known-harness filter (all of which also sanitize to `harnesses: []`)
+     * -- that distinction is `harnessesRecordedEmpty`'s job; both must hold
+     * for the stickiness gate to fire.
+     */
+    previousIsRecordedManifest?: boolean;
+}
+export interface ResolvedInitInputs {
+    harnesses: Harness[];
+    profile: Profile;
+    models: Record<Role, string>;
+    tiers: boolean;
+    opencodeModels?: Record<Role, string | undefined>;
+    opencodeClassModels?: Record<ModelClass, string | undefined>;
+    /**
+     * Warning lines to print, in order, exactly as `init` printed them to
+     * stderr before this extraction (each written as `${line}\n`). Returned
+     * as data rather than printed here so the caller decides where/whether to
+     * print them.
+     */
+    warnings: string[];
+}
+/**
+ * Resolves everything `runInit` needs (harnesses, profile, models, tiers,
+ * the opencode model resolutions) from the CLI-parsed options, the target
+ * directory, whether the session is interactive, and the previously
+ * installed manifest. Used by `init`'s action today, and reusable by a
+ * later `apply --target` command without duplicating this logic.
+ *
+ * Every override-vs-persist rule below matches `init`'s pre-extraction
+ * behaviour: an explicit flag always overrides; a plain re-run (flag
+ * omitted) keeps the previously installed value; a fresh install with no
+ * prior manifest falls back to the shipped default.
+ */
+export declare function resolveInitInputs(params: ResolveInitInputsParams): Promise<ResolvedInitInputs>;