orchestrator-workflow 0.39.0 → 0.40.1

package/CHANGELOG.md

@@ -7,6 +7,129 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.40.1] - 2026-09-24
+
+- Restored the `0.37.0` section byte for byte to the text released at tag
+  `orchestrator-workflow/v0.37.0`, after a later change had rewritten its
+  wording. The test assertion that read that section was removed; the rule
+  clauses stay pinned against the reference files and the docs/okf bundle
+  doc, since a released section stays as shipped.
+
+- The shared verification-set comparison sentence in implementer.md,
+  reviewer.md, and contracts.md now compares effective config and scripts,
+  and preflight executable identity/definition, at the tree the
+  verification set executes in, and defers repository identity to the
+  path rule instead of restating it against the role's own checkout. The
+  two rules read as a single rule again instead of two that could be read
+  as disagreeing.
+
+## [0.40.0] - 2026-09-23
+
+- A verification set can no longer look green while checking the wrong
+  tree. evidence-and-probes.md's Verification sets section now requires,
+  when the diff for a repository comes from a linked worktree (however the
+  run-base marker is keyed, or with only the unkeyed marker), that every
+  literal path into that repository in the set's argv and cwd is
+  re-resolved under that worktree's top level before freezing and recorded
+  in the frozen snapshot. The implementer and reviewer prompts,
+  contracts.md, and that section share one rule: in the comparison before
+  acquisition or execution, repository identity means the repository and
+  its path, compared with the worktree the diff comes from; a set frozen
+  against another checkout withdraws the approval and is a misfire, while
+  a revision difference alone does not. Tests pin the re-resolution rule in
+  the Verification sets section and the identity rule in all four sources
+  and in every rendered implementer and reviewer variant (#336).
+
+- Run-internal identifiers (the criterion, task, decision, and review round
+  IDs the run files assign) no longer have to be kept out of committed work
+  by hand in every briefing. The implementer prompt now forbids writing them
+  into code, comments, tests, or commit messages and asks for the ticket or
+  issue reference and a description of the behaviour instead; the reviewer
+  prompt's maintainability checklist item names them as a finding class.
+  evidence-and-probes.md gains a Run-internal identifiers section that
+  derives each ID format from the template assigning it and documents a
+  shell check (usable as a verification-set extra, with the run-base as its
+  argument) over the lines added since the run-base outside `.ai/` and the
+  commit messages in `run-base..HEAD`, stating its exit codes, what it does
+  not cover, and how a false positive is recorded. A new test runs the
+  documented script, extracted from the reference file, against a fixture
+  repository with and without such identifiers, so the documentation and
+  the command cannot drift apart (#337).
+
+- The reviewer role now states one consistent write and replay rule set,
+  with every site (the Rules-section write boundary, the general mutant-
+  application bullet, step 7's single-mode replay duty, and the reviewer
+  prompt's copy of that duty) agreeing instead of contradicting one
+  another. The write boundary is a location rule, not a single named
+  exception: never write into the reviewed tree, its index, its refs, or
+  its object store; outside it, write only to the writer's own scratchpad
+  or the run's `evidence/`, and build/test artifacts a declared check
+  produces are expected, not a violation. For `evidence/`, the briefing's
+  own run-directory path wins over the `.ai/run` pointer (repository data,
+  which may be stale); the pointer is used only when the briefing names no
+  run directory and matches the run the briefing refers to, otherwise the
+  mismatch is reported and nothing is written, and the resolved path must
+  land under `<run-dir>/evidence/` with no symlinked component. The
+  forbidden-command list still explicitly names ref/object-changing
+  commands (`git fetch`, `git merge-tree --write-tree`, `git update-ref`,
+  `git gc`, plus the existing tree/index-mutating ones) and any in-place
+  edit of a tracked file, including a hand-applied mutant; a merge-conflict
+  question about an open PR is still routed back to the orchestrator
+  instead of being answered with `git fetch`. A mutant is applied only
+  through the probe runner, in every run mode; when no runner is available
+  the probe is reported `not_applicable` (missing evidence, not a pass),
+  never hand-applied, with no "when one is available" fallback or
+  "scratch copy" alternative left standing anywhere in the probe-replay
+  text. A briefing-authorized in-place runner mode (for when worktree
+  isolation is unusable) is now an explicit, bounded exception to "never in
+  the reviewed tree," not a redefinition of it: only the orchestrator's
+  briefing authorizes it, only the runner applies the mutant, the runner
+  must report `restored_verified: true` (a missing or `false` value is a
+  finding), the tree must be clean and at the reviewed head, and no other
+  agent may be active in that tree at the same time. `evidence/` is now
+  documented as an optional run subdirectory in the run-layout reference,
+  naming the orchestrator, the implementer, and the reviewer as the roles
+  that write into it and stating that the explorer and the advisor, being
+  read-only, never do. The location rule also names, explicitly, that a
+  write a declared check or the probe runner's own default isolation
+  leaves behind is expected wherever that tool places it, not an exception
+  to the rule. The in-place exception's conditions and the run mode
+  `single` duty's `not_applicable` fallback are now pinned at every site
+  that states them (the reviewer prompt, its rendered install variants,
+  and step 7's mirror), alongside the evidence-path symlink and mismatch
+  clauses and the merge-conflict routing sentence. The README's read-only
+  posture section states the reviewer's narrower write boundary the same
+  way (#339).
+
+- A verification set named in the briefing by reference plus its frozen
+  digest and repository identity now reads, at every site that states the
+  rule, as the orchestrator's approval of every argv resolved from that
+  frozen snapshot, closing the gap where an implementer reported the
+  briefed extras as unresolved and repeated the same open question every
+  round even though the reviewer ran them under the same briefing. A
+  digest mismatch withdraws the approval and is reported as a misfire, and
+  the approval never reaches beyond the frozen snapshot: an unfrozen set,
+  a changed script, or anything else the snapshot does not capture still
+  needs the orchestrator's explicit approval before acquisition or
+  execution. The subagent input contract's `verification_set` section, and
+  the implementer and reviewer prompts' verification-set rules, now state
+  the approval condition in the same wording (#335).
+
+- Before acquisition or execution, implementer.md, reviewer.md, and
+  contracts.md state, in identical wording, that the role compares the
+  frozen snapshot's effective config and scripts, preflight executable
+  identity/definition, and repository identity with the tree it runs in;
+  any mismatch withdraws the approval like a digest mismatch and is
+  reported as a misfire, and a change the task's own diff makes to one of
+  those components is outside the approval. The `verification_set` shape
+  in the subagent input contract and both task-slicer output copies now
+  also carries a `snapshot` sub-field, alongside `digest` and
+  `repository_identity`, naming the run-local path of the frozen snapshot
+  record those compared values are read from; evidence-and-probes.md's
+  Verification sets section defines what counts as a "script" for that
+  comparison and states that the orchestrator records the snapshot at the
+  run-local path it names in the briefing (#335).
+
 ## [0.39.0] - 2026-09-23
 
 - The docs-only review default now states its condition directly instead
@@ -209,27 +332,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   the check itself unchanged is a `03-decisions.md` entry, not a revision";
   the orchestrator records that entry, states in it why no evidence is
   invalidated, and communicates the corrected wording in the next
-  delegation. Step 7 now says: "For a review round whose entire delta contains only explanatory documentation, comments, or citations and contains no source- or test-file edits and no semantic change to executable commands, configuration, policy, instructions, or behavior, default to the `-medium` reviewer tier with `review_method: normal` where tier variants are installed". That refines the general tier default for this one class only. "A review round that touches an instruction, policy, template or prompt file (for example a SKILL.md instruction) keeps the general default, whatever the file type, and the minimums named above are unaffected";
+  delegation. Step 7 now says: "For a review round whose entire delta is a
+  docs-only delta in the sense of step 8's docs-only closure, default to the
+  `-medium` reviewer tier with `review_method: normal` where tier variants
+  are installed". That refines the general tier default for this one class
+  only, a round that touches an instruction, policy, template or prompt file
+  keeps the general default, and the minimum review methods are untouched;
   the AGENTS.md section does not yet point to this refinement.
   `references/review-and-recovery.md` gains a "Pinned-prose changes" section
   for a change whose acceptance rests on tests that pin documentation
   wording: "A prose mutant survives exactly when its bytes sit in no
   assertion", so review rounds that hunt for the next unpinned sentence do
-  not converge. The section asks for one normative site per rule, a claim list in the acceptance criterion as the pin obligation. "Every normative sentence the change adds or alters at that site is pinned; one left unpinned is named in the criterion with the reason it is not load-bearing." A reviewer briefing
-  bounds the prose mutant space to that list, and "When the briefing
-  bounds the
-  prose mutant space to a claim list, respect that bound and put scope notes in
-  `residual_risks`, unless an unlisted sentence is shown to be load-bearing."
-  Copies are bound to the normative site by one shared test constant, and: "Cap
-  test-adequacy review rounds on the change at two." "A test-adequacy review
-  round is one whose returned findings are all `tests` findings of severity
-  `low` or `medium` about pin gaps on the pinned prose; a round returning any
-  other finding is an ordinary round outside the cap." "The cap changes neither
-  the Round-2 halt rule, the Review-round escalation budget nor the
-  Fix-regression decision point: a test-adequacy review round still counts as a
-  negative round where it is one." It exempts semantic findings and leaves the
-  review gate as it is. Step 7 points to the section without
-  restating it. Evidence (issue #300 and the change that added the Fix-regression
+  not converge. The section asks for one normative site per rule, a claim
+  list in the acceptance criterion as the pin obligation (every normative
+  sentence the change adds or alters at that site is a claim, an omission is
+  named with its reason), a reviewer briefing that bounds the prose mutant
+  space to that list, copies bound to the normative site by one shared test
+  constant, and: "Cap test-adequacy review rounds on the change at two." It
+  defines the capped round, exempts semantic findings, and changes neither
+  the Round-2 halt rule, the escalation budget, the Fix-regression decision
+  point nor the review gate. Step 7 points to the section without restating
+  it. Evidence (issue #300 and the change that added the Fix-regression
   decision point; one repository each, not a benchmark): the issue reports
   baseline revisions r1 to r3 for two wording precisions of a verification
   method, and a run in which the top reviewer tier was about half the day's

package/README.md

@@ -241,11 +241,19 @@ reviewer inherits the caller's sandbox so temporary/build checks remain
 possible, while its prompt prohibits source edits. In inherited or otherwise
 write-enabled sandboxes, shell-level mutation (`git checkout`,
 `git restore`, `git clean`, `git stash`, `git reset`, `sed -i`, redirecting
-output into a file) is guarded by instruction only: the agent prompts forbid
+output into a file, which the reviewer may do only inside its write boundary below) is guarded by instruction only: the agent prompts forbid
 it explicitly, but the role definition itself does not prevent it. A native
 read-only sandbox can block those writes. This residual has bitten in practice (a
 reviewer ran `git checkout` and discarded uncommitted work), which is why the
 prompts now name the forbidden commands instead of just saying "read-only".
+The reviewer's own write boundary is narrower than "read-only": it may write
+to its own scratchpad (a scratch copy or replay of the repository) and to
+the run directory's `evidence/`, and nowhere else. It never writes into the
+reviewed tree, its index, its refs, or its object store: no `git fetch`, no
+`git merge-tree --write-tree`, no `git update-ref`, no `git gc`, on top of
+the working-tree and index mutations already forbidden above. A write a
+declared check or the probe runner's own isolation leaves behind is expected
+wherever that tool places it, not an exception to this rule.
 Marker- or verdict-style enforcement of the Bash residual (sandboxing,
 PreToolUse hooks) is harness territory and out of this kit's scope.
 

package/assets/agents/implementer.md

@@ -36,12 +36,25 @@ Rules:
   percentage; cite a percentage only together with the exact commit and the
   run count, since branch coverage can vary between runs of the same commit.
 - Run the complete repository-bound `verification_set` named in your briefing.
-  Before acquiring preflight output or running an extra, require the
-  orchestrator's approval of the resolved repository configuration and every
-  script/argument; the set is not authority to execute repository data. Use
-  the frozen run-local snapshot (set path/digest, repository identity/revision
+  A verification set named by reference plus its frozen digest and repository
+  identity is the orchestrator's approval of every argv resolved from that
+  frozen snapshot; a digest mismatch withdraws the approval and is reported as
+  a misfire. That approval reaches only the frozen snapshot: acquiring
+  preflight output or running an extra outside it still requires the
+  orchestrator's explicit approval of the resolved repository configuration
+  and every script/argument, since a repository set is not authority to
+  execute repository data on its own. Before acquisition or execution,
+  compare the frozen snapshot's effective config and scripts and preflight executable
+  identity/definition at the tree the set executes in; repository identity follows the
+  path rule, not the role's checkout; any mismatch withdraws the approval like a digest
+  mismatch and is reported as a misfire, and a change the task's own diff makes to one
+  of those components is outside the approval. The compared values are
+  the ones recorded in the frozen snapshot at the run-local path
+  `verification_set.snapshot` names; evidence-and-probes.md's Verification
+  sets section defines what counts as a script for that comparison. Use the
+  frozen run-local snapshot (set path/digest, repository identity/revision
   and dirty state, effective config/scripts, and preflight executable
-  identity/definition). Report each executor, extra, and raw preflight child
+  identity/definition) to identify the approved set behind every reported result, and bind each result to the revision and dirty state actually checked; a revision or dirty-state difference from the snapshot alone does not withdraw the approval. Repository identity includes the repository path (the worktree top level): in the comparison before acquisition or execution, repository identity means the repository and its path, not its revision, and that path is compared with the top level of the worktree the diff comes from, not with whichever checkout the role runs in; a set frozen against another checkout than the one the diff comes from (for example the main checkout while the diff comes from a linked worktree) withdraws the approval and is a misfire, not a pass, while a revision difference alone does not. Report each executor, extra, and raw preflight child
   by `(kind, name, occurrence)`, in order, with cwd and result artifact.
   Preserve a missing-tool preflight limitation even when it has no child
   result. A missing/extra/mismatched/unresolved result is a misfire; a failure
@@ -187,7 +200,7 @@ Rules:
   check. A background monitor is no substitute for those returns.
 - Only write a verification claim (for example "Verified by ...") in a code
   comment, commit message, or your report for a check you actually ran and
-  measured yourself; never claim a run you did not execute.
+  measured yourself; never claim a run you did not execute. Never write run-internal identifiers (criterion, task, decision, or review round IDs from the run files) into code, comments, tests, or commit messages; reference the ticket or issue and describe the behaviour instead. evidence-and-probes.md's Run-internal identifiers section defines these IDs and documents a check for them.
 - Do not refactor beyond the task scope, do not fix unrelated issues, do not
   expand the task. Report anything noteworthy as a risk or open question
   instead.

package/assets/agents/reviewer.md

@@ -53,12 +53,28 @@ Check, at minimum:
   returned `criterion_evidence` references to every assigned frozen criterion;
   required empty references remain unresolved and block acceptance.
 - Verification set: independently run the complete repository-bound
-  `verification_set` named in the briefing. Before acquisition or execution,
-  confirm the orchestrator approved the resolved effective configuration and
-  scripts; a repository set is not execution authority. Compare the frozen
-  snapshot's set path/digest, repository identity/revision/dirty state,
-  effective config/scripts, and preflight executable identity/definition.
-  Report every ordered `(kind, name, occurrence)` executor, extra, and raw
+  `verification_set` named in the briefing. A verification set named by
+  reference plus its frozen digest and repository identity is the
+  orchestrator's approval of every argv resolved from that frozen snapshot; a
+  digest mismatch withdraws the approval and is reported as a misfire. That
+  approval reaches only the frozen snapshot: acquiring or executing anything
+  outside it still requires confirming the orchestrator approved the resolved
+  effective configuration and scripts, since a repository set is not
+  authority to execute repository data on its own. Before acquisition or
+  execution, compare the frozen snapshot's effective config and scripts and preflight
+  executable identity/definition at the tree the set executes in; repository identity
+  follows the path rule, not the role's checkout; any mismatch withdraws the approval
+  like a digest mismatch and is reported as a misfire, and a change the task's own diff
+  makes to one of those components is outside the approval. The compared
+  values are the ones recorded in the frozen snapshot at the run-local path
+  `verification_set.snapshot` names; evidence-and-probes.md's Verification
+  sets section defines what counts as a script for that comparison. Use the
+  frozen run-local snapshot (set path/digest, repository identity/revision
+  and dirty state, effective config/scripts, and preflight executable
+  identity/definition) to identify the approved set behind every reported result, and bind
+  each result to the revision and dirty state actually checked; a revision or dirty-state difference from the snapshot alone does not withdraw the approval. Repository identity includes the repository path (the worktree top level): in the comparison before acquisition or execution, repository identity means the repository and its path, not its revision, and that path is compared with the top level of the worktree the diff comes from, not with whichever checkout the role runs in; a set frozen against another checkout than the one the diff comes from (for example the main checkout while the diff comes from a linked worktree) withdraws the approval and is a misfire, not a pass, while a revision difference alone does not. Report every
+  ordered `(kind, name, occurrence)`
+  executor, extra, and raw
   preflight child with cwd and result artifact. A missing tool may be a
   limitation with no child, never a pass; disabled required categories are
   gaps. Missing/extra/mismatched/unresolved results are misfires, while a
@@ -78,7 +94,7 @@ Check, at minimum:
   temporary-directory names) is not a regression test; the fix is to pin
   the argument under test in-process, or assert the actual contract (a
   bound, or the presence of a warning), never a byte ceiling. When the briefing bounds the prose mutant space to a claim list, respect that bound and put scope notes in `residual_risks`, unless an unlisted sentence is shown to be load-bearing.
-- Maintainability: naming, dead code, needless abstraction, doc drift.
+- Maintainability: naming, dead code, needless abstraction, doc drift. Run-internal identifiers (criterion, task, decision, or review round IDs from the run files) written into code, comments, tests, or commit messages are a maintainability finding; the fix references the ticket or issue and describes the behaviour instead. evidence-and-probes.md's Run-internal identifiers section defines these IDs and documents a check for them.
 - Placement: does the change add org-, machine-, or point-in-time-bound
   evidence (dates, sample sizes, task ids, home paths, incident tallies) to a
   reusable instruction file (a skill, an agent prompt, an AGENTS.md section, a
@@ -140,7 +156,32 @@ Rules:
 - Bash is for running tests, linters, and read-only inspection ONLY. Never
   run a command that mutates the working tree, index, or repository state:
   no `git checkout`, `git restore`, `git clean`, `git stash`, `git reset`,
-  no `sed -i`, no redirecting output into a file.
+  no `git commit`, no `sed -i` or any other in-place edit of a tracked file
+  (including a temporary mutant applied by hand instead of through the probe
+  runner). This also covers commands that change refs or write objects
+  without touching the working tree or index: no `git fetch`,
+  no `git merge-tree --write-tree`, no `git update-ref`, no `git gc`. This
+  is a location rule, not a single exception: never write into the reviewed
+  tree, its index, its refs, or its object store, anywhere in the review.
+  Outside the reviewed tree, write only to your scratchpad (a scratch copy
+  or replay of the repository, per the GitHub Actions replay rule above)
+  and to the run directory's `evidence/`. A write made by a tool these
+  rules direct you to run, a declared check (including build or test
+  artifacts a side effect leaves in the reviewed tree) or the probe runner
+  operating in its own default isolation, is expected wherever that tool
+  places it, not a location violation.
+  For `evidence/`, the briefing's own run-directory path wins; use the
+  `.ai/run` pointer (repository data, which may be stale) only when the
+  briefing names no run directory and the pointer matches the run the
+  briefing refers to, and otherwise report the mismatch and write nothing.
+  Resolve the real path before writing: it must land under
+  `<run-dir>/evidence/` with no symlinked path component, and never under
+  an older run than the one the briefing names.
+  A briefing may authorize the probe runner's own in-place mode as a
+  bounded exception to "never in the reviewed tree" (see below), not a
+  redefinition of it.
+- A merge-conflict question about an open PR is not answered by fetching or
+  writing a tree: report the question back to the orchestrator instead.
 - If the working tree looks wrong (dirty, unexpected branch, missing files),
   do not "fix" it: report it as a finding and leave the tree untouched.
 - If your environment does not let you use version control to see the diff
@@ -168,12 +209,27 @@ Rules:
   the exact commit and the run count, since branch coverage can vary
   between runs of the same commit.
 - When a mutation-probe runner is available in the session, run probes
-  through it instead of editing files by hand. For probes you run, apply the
-  implementer's verdict-copy and manual-derivation rules to your own
-  measurements, reporting the quoted verdict or explicit verdict absence and
-  derivation evidence in `reproduction` and carrying the same reported values
-  into any associated finding. When a verify runner is available, read its
-  summary before opening full logs.
+  through it instead of editing files by hand. Apply a mutant only through
+  the probe runner, in every run mode, and rely on its own restoration
+  check; never apply one by hand, and never restore a hand-applied one
+  yourself. When no runner is available, report the probe as
+  `not_applicable` instead of hand-applying it: that is missing evidence,
+  not a pass. A hand-applied mutant is a finding against the review,
+  whatever its outcome, because it carries no verified restoration. For
+  probes you run, apply the implementer's verdict-copy and manual-derivation
+  rules to your own measurements, reporting the quoted verdict or explicit
+  verdict absence and derivation evidence in `reproduction` and carrying the
+  same reported values into any associated finding. When a verify runner is
+  available, read its summary before opening full logs.
+- A briefing may authorize the probe runner's own in-place mode when
+  worktree isolation is unusable. That stays a bounded exception to "never
+  in the reviewed tree," not a redefinition of it: only the orchestrator's
+  briefing authorizes it, only the runner itself applies the mutant (never
+  you by hand), the runner must report `restored_verified: true` for every
+  such probe (a missing or `false` value is a finding), the tree must be
+  clean and at the reviewed head before the runner starts, and no other
+  agent may be active in that tree at the same time (see the concurrency
+  rule in step 7 of the detailed workflow).
 - A reviewer briefing may identify a replayed probe through a resolved
   immutable probe-plan reference (path plus revision/hash and mutant
   locator/index) rather than repeat its inline definition. Verify the plan and
@@ -184,14 +240,17 @@ Rules:
   the change itself
   and nobody has cross-checked its probe evidence: replay every named
   orchestrator probe, where named means the briefing gives its full
-  definition or a resolved immutable plan-and-result reference (in a
-  scratch copy or an isolating probe runner, never in the reviewed tree).
-  It reports per probe, in `reproduction`, the probe, the replayed verdict
+  definition or a resolved immutable plan-and-result reference, through the
+  probe runner only, never in the reviewed tree except under the authorized
+  in-place mode above; when no runner is available, report the probe as
+  `not_applicable`. It reports per probe, in `reproduction`, the probe, the
+  replayed verdict
   or explicit verdict absence with manual derivation evidence, and whether
   the measured `result` and `expectation` match the recorded fields; a
   mismatch is a finding of at least `high` and sets
   `matches_implementer_claim: mismatched`. Do not skip a named probe in
-  that mode, under any `review_method`; any mismatch also sets
+  that mode, under any `review_method`; a probe that cannot run through the
+  runner is reported `not_applicable`, not skipped; any mismatch also sets
   `matches_implementer_claim: mismatched`. A mismatch is a finding of at
   least `high`; a probe given only by id is `not_applicable` and is
   missing evidence, not a pass, and so is a briefing in that mode that

package/assets/agents/task-slicer.md

@@ -46,7 +46,9 @@ Rules:
   selection above to those fields for a recorded original contract.
 - Include a repository-bound `verification_set` reference in every implementer
   and reviewer briefing: its checked-in path, repository identity, and
-  run-local frozen snapshot. The orchestrator approves effective config and
+  run-local frozen snapshot. The digest recorded in the briefing is what
+  carries the orchestrator's approval of the resolved argv to the implementer
+  and reviewer. The orchestrator approves effective config and
   scripts before any preflight acquisition or command execution; the set does
   not grant that authority. Include an ordered bundle check whenever the
   repository has `docs/okf/`, regardless of task scope.
@@ -95,6 +97,9 @@ tasks:
       - ""
     verification_set:
       reference: ""
+      digest: ""
+      repository_identity: ""
+      snapshot: ""
     risk: low | medium | high
 recommended_order:
   - T-001

package/assets/skill/references/contracts.md

@@ -60,6 +60,9 @@ context:
   relevant_docs: []
 verification_set:
   reference: ""
+  digest: ""
+  repository_identity: ""
+  snapshot: ""
 constraints:
   - ""
 allowed_changes:
@@ -72,8 +75,28 @@ expected_output:
 
 `verification_set.reference` identifies the checked-in set selected for this
 repository. The briefing also carries its repository identity and run-local
-frozen snapshot; those resolved values are evidence metadata, not a new
-authority to execute repository configuration or scripts.
+frozen snapshot: naming that set by reference plus its frozen digest and
+repository identity, as delegated in the briefing, is the orchestrator's
+approval of every argv resolved from that frozen snapshot; a digest mismatch
+withdraws the approval and is reported as a misfire.
+`verification_set.snapshot` names the run-local path of the frozen snapshot
+record. The reference-plus-digest form shown above is sufficient by itself;
+neither role needs the argv repeated argument-by-argument to run it. That
+approval reaches only the frozen
+snapshot: an unfrozen set, a changed script, or anything the snapshot does not
+capture still needs the orchestrator's explicit approval before acquisition or
+execution, since a repository set is not authority to execute repository data
+on its own. Before acquisition or execution, compare the frozen snapshot's effective
+config and scripts and preflight executable identity/definition at the tree the set
+executes in; repository identity follows the path rule, not the role's checkout; any
+mismatch withdraws the approval like a digest mismatch and is reported as a misfire,
+and a change the task's own diff makes to one of those components is outside the
+approval. The compared values are the ones recorded in the frozen snapshot at
+the run-local path `verification_set.snapshot` names; evidence-and-probes.md's
+Verification sets section defines what counts as a script for that
+comparison. This mirrors the re-resolve rule in evidence-and-probes.md:
+re-resolve when an executable definition, effective config/script, tool
+identity, set digest, or approved snapshot changes. Repository identity includes the repository path (the worktree top level): in the comparison before acquisition or execution, repository identity means the repository and its path, not its revision, and that path is compared with the top level of the worktree the diff comes from, not with whichever checkout the role runs in; a set frozen against another checkout than the one the diff comes from (for example the main checkout while the diff comes from a linked worktree) withdraws the approval and is a misfire, not a pass, while a revision difference alone does not.
 
 ## Implementer output contract
 
@@ -281,6 +304,9 @@ tasks:
       - ""
     verification_set:
       reference: ""
+      digest: ""
+      repository_identity: ""
+      snapshot: ""
     risk: low | medium | high
 recommended_order:
   - T-001

package/assets/skill/references/evidence-and-probes.md

@@ -221,7 +221,17 @@ directory and the subagents.
    `04-implementation-summary.md` before requesting review, the reviewer
    briefing states the run mode and names each of those probes, and the
    reviewer must replay every named orchestrator probe, through the probe
-   runner when one is available and never in the reviewed tree. It reports
+   runner only, never in the reviewed tree; when no runner is available,
+   report the probe as `not_applicable`, which is missing evidence, not a
+   pass. A briefing
+   may authorize the runner's own in-place mode as a bounded exception to
+   "never in the reviewed tree" when worktree isolation is unusable: only
+   the orchestrator's briefing authorizes it, only the runner applies the
+   mutant, the runner must report `restored_verified: true` for every such
+   probe (a missing or `false` value is a finding), the tree must be clean
+   and at the reviewed head before the runner starts, and no other agent may
+   be active in that tree at the same time (see the concurrency rule below).
+   It reports
    per probe, in `reproduction`, the probe, the replayed verdict or
    explicit verdict absence with manual derivation evidence, and whether
    the measured `result` and `expectation` match the recorded fields; a
@@ -303,8 +313,19 @@ never grants permission to run an arbitrary build or script.
 Before acquiring even preflight output, the orchestrator inspects and approves
 the repository's effective configuration and every resolved script/argument,
 then freezes the complete set definition. Repository configuration and its
-commands are data, not authority. Any optional earlier inventory acquisition
-also needs prior command approval and is not full-set evidence. After the
+commands are data, not authority. Naming that set by reference plus its frozen
+digest and repository identity is how this approval reaches the implementer
+and reviewer: it is the orchestrator's approval of every argv resolved from
+that frozen snapshot, and a digest mismatch withdraws the approval and is
+reported as a misfire. This is the identical approval condition contracts.md's
+Subagent input contract pins in its own wording; contracts.md additionally
+pins the per-role comparison rule that implementer.md and reviewer.md
+restate before acquisition or execution. That approval reaches only
+the frozen snapshot; an unfrozen set, a changed script, or anything else the
+snapshot does not capture still needs the orchestrator's own explicit
+approval before acquisition or execution. Any optional earlier inventory
+acquisition also needs prior
+command approval and is not full-set evidence. After the
 definition is approved and frozen, each role attempt executes
 `before_preflight` extras in declaration order, then preflight, then
 `after_preflight` extras in declaration order, and preserves the raw preflight
@@ -315,10 +336,14 @@ not command discovery or a substitute for inspecting the actual configuration.
 
 Malformed set JSON or shape is unresolved and does not authorize execution.
 
-Freeze the resolution in the run before execution. Its identity includes the
-set reference path and digest, repository identity/revision and dirty state,
-the effective configuration and scripts, the preflight executable path,
-version, digest, and approved definition, plus every resolved extra. Identify
+Freeze the resolution in the run before execution; the orchestrator records
+that snapshot at a run-local path it names in the briefing. Its identity
+includes the set reference path and digest, repository identity/revision and
+dirty state, the effective configuration and scripts, the preflight
+executable path, version, digest, and approved definition, plus every
+resolved extra. "Scripts" here means every package-manager script entry plus
+every file an extra's or preflight's argv or such a script entry invokes directly, and repository configuration files the executed tools load count as effective configuration; code under test
+is not a component. Identify
 each result by `(kind, name, occurrence)` in declared order: duplicate
 `(kind, name)` values are distinct occurrences, never a map entry overwritten
 by name. Bind every result attempt to its checked revision and dirty state. A
@@ -326,7 +351,7 @@ source edit makes an old result inapplicable to the new state, but does not
 itself require re-resolving an unchanged set; re-resolve when an executable
 definition, effective config/script, tool identity, set digest, or approved
 snapshot changes. An unresolvable reference is stale and invalidates the
-result.
+result. When the diff for a repository comes from a linked worktree (whether that repository's run-base marker is keyed by the worktree's basename or the main repository's, or the run carries only the unkeyed marker), re-resolve every literal path into that repository in the set's argv and cwd to the corresponding path under that worktree's top level before freezing, and record the resolved paths in the frozen snapshot; a literal path left pointing at another checkout checks another tree, not the delta. Repository identity includes the repository path (the worktree top level): in the comparison before acquisition or execution, repository identity means the repository and its path, not its revision, and that path is compared with the top level of the worktree the diff comes from, not with whichever checkout the role runs in; a set frozen against another checkout than the one the diff comes from (for example the main checkout while the diff comes from a linked worktree) withdraws the approval and is a misfire, not a pass, while a revision difference alone does not.
 
 Both implementer and reviewer run the complete frozen set and report every
 named executor, extra, and raw preflight child occurrence, with cwd and result
@@ -346,3 +371,80 @@ of the verification set, so the set's missing-or-extra rule does not apply to it
 A persisted probe plan is an optional, runner-supported executable artifact. Its reference carries a path plus immutable revision or hash and mutant locator/index. Assignments and summaries may point to it and a result artifact instead of resending a definition; legacy inline reports remain valid.
 
 A plan alone is never evidence. A result binds plan identity to checked state, cwd, attempt, expectation, applied mutant, and restoration. Missing, stale, or unresolvable references block proof and cannot count as skipped. Never silently rewrite an existing plan for new code to turn red green; record intentional supersession and rationale when a source move requires replacement.
+
+# Run-internal identifiers
+
+Run-internal identifiers are the IDs the run files assign: criterion IDs in
+`00-goal.md` (`AC-` plus three digits), task IDs in `02-tasks.md` (`T-` plus
+three digits), decision IDs in `03-decisions.md` (`D-` plus three digits), and
+review round labels (`R` plus the round number, a common key for the
+`<round>` markers in `05-review-findings.md`). They mean something only
+inside the run directory, which is not part of the target repository. Code,
+comments, tests, and commit messages reference the ticket or issue and
+describe the behaviour instead; implementer.md states this as a rule and
+reviewer.md as a maintainability finding class.
+
+The orchestrator may add the check below to a verification set as an extra
+of kind `command` in the `after_preflight` phase, with `cwd` at the
+repository root and the run-base recorded in `00-goal.md` for that
+repository as its only argument. Its argv is `["sh", "-c", <the script
+below as one string>, "sh", <run-base>]`:
+
+```sh
+base="$1"
+unset GREP_OPTIONS
+ids='(^|[^A-Za-z0-9_])((AC|D|T)-[0-9]{3}|R[0-9]+)([^A-Za-z0-9_]|$)'
+top=$(git rev-parse --show-toplevel) || exit 2
+cd "$top" || exit 2
+git rev-parse --verify --quiet "$base^{commit}" >/dev/null || exit 2
+d=$(git diff --no-color --no-ext-diff --no-textconv --text -M \
+  --src-prefix=a/ --dst-prefix=b/ "$base" HEAD -- . ':(exclude).ai') || exit 2
+m=$(git log --no-show-signature --format=%B "$base..HEAD") || exit 2
+a=$(printf '%s\n' "$d" |
+  LC_ALL=C awk '/^diff --git /{h=1; next}
+       h && /^\+\+\+ /{f=substr($0, 7); next}
+       /^@@/{h=0; next}
+       !h && /^\+/{print f ": " substr($0, 2)}') || exit 2
+hits=0
+for t in "$a" "$m"; do
+  printf '%s\n' "$t" | LC_ALL=C grep -E "$ids"
+  s=$?
+  [ "$s" -eq 0 ] && hits=1
+  [ "$s" -gt 1 ] && exit 2
+done
+exit "$hits"
+```
+
+Exit `0` means no hit, exit `1` means at least one hit, each printed (a diff
+hit prefixed by its file path, shown escaped and without its leading `"b`
+for a path git quotes), and exit `2` means the run-base does not
+resolve to a commit or a git, awk, or grep command failed. The check fails
+closed: it reads the whole diff and log into memory and checks the status of
+every stage, so a failure part way through (an unreadable object, or a text
+tool rejecting a byte, for example) exits `2` instead of passing on partial
+output; the text stages run byte-wise (`LC_ALL=C`) so no locale can make
+them reject the input. It changes to the top level of the
+repository first, so a `cwd` in a subdirectory scans the same range. The
+diff options override the external diff, textconv, binary, rename, color,
+and prefix settings of the user's git configuration and the repository's
+attributes (`--text` diffs a file marked `-diff` or `binary` as text), and
+the log option suppresses signature output, so those settings cannot hide an
+added line from the scan or add lines to it.
+
+It covers the lines added between the run-base and `HEAD` outside the
+top-level `.ai/` directory, and the message of every commit reachable from
+`HEAD` and not from the run-base. That range includes upstream work merged
+into the branch after the run-base, whose added lines and commit messages
+are scanned as well and can produce hits the branch did not write. It does
+not cover uncommitted changes, removed lines, an identifier directly next to
+a NUL byte (the shell drops NUL bytes from the captured diff), pull request
+titles or bodies, branch names, or identifiers in any other format.
+The patterns are case-sensitive and can match unrelated tokens, such as a
+product or part name built the same way; because `--text` also diffs files
+git detects as binary by content, an added image, font, or archive usually
+produces hits made of its raw bytes, and a repository whose own
+documentation discusses these formats (a copy of these templates, for
+example) matches as well. A hit is a failure of the extra; when the
+orchestrator confirms a hit is a false positive it records that decision,
+and it may narrow the pathspec with further `':(exclude)<path>'` entries
+when it approves the extra.

package/assets/skill/references/run-state-and-harness.md

@@ -75,6 +75,7 @@ All state for one unit of work lives in a run directory:
   04-implementation-summary.md
   05-review-findings.md
   06-handoff.md
+  evidence/
 ```
 
 Create it at the start of a run by copying `.ai/workflow/templates/` and fill
@@ -82,6 +83,15 @@ 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.
 
+`evidence/` is an optional subdirectory, not one of the seven templated
+files: nothing copies or requires it. The orchestrator, the implementer, and
+the reviewer write into it (test logs, probe verdicts, reproduction output,
+reviewer-reproduced evidence) when a briefing or an acceptance criterion
+asks for a saved artifact instead of just a report field; the reviewer's
+write-boundary rule names it as the one write-allowed location outside the
+reviewed tree, besides the writer's own scratchpad. The explorer and the
+advisor are read-only roles and never write into it, or anywhere else.
+
 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`:

package/assets/templates/02-tasks.md

@@ -38,6 +38,8 @@ acceptance_criteria:
 **Verification Set**
 
 <!-- Checked-in path, repository identity, and run-local frozen snapshot. The
+digest recorded in the briefing is what carries the orchestrator's approval
+of the resolved argv to the implementer and reviewer. The
 orchestrator approves effective config/scripts before any acquisition or
 execution; include an ordered docs/okf bundle check whenever that directory
 exists. -->

package/dist/review-report.d.ts

@@ -166,7 +166,7 @@ interface ExtractedYaml {
  * shorter run length from every offset inside the run, each retry
  * rescanning the lazy body: work quadratic in the run's length, which a
  * single pasted return of a few hundred backticks already turns into
- * seconds (CHANGELOG [Unreleased] names the measurement). Keeping the
+ * seconds (CHANGELOG 0.37.0 names the measurement). Keeping the
  * run whole also makes the "closing run at least as long as the opening
  * one" rule above literal: an opener longer than any closing run in the
  * input is no fence at all, where splitting the run instead matched it

package/dist/review-report.js

@@ -443,7 +443,7 @@ export const ARRAY_ELEMENT_EXPECTED = KIND_EXPECTED.string;
  * shorter run length from every offset inside the run, each retry
  * rescanning the lazy body: work quadratic in the run's length, which a
  * single pasted return of a few hundred backticks already turns into
- * seconds (CHANGELOG [Unreleased] names the measurement). Keeping the
+ * seconds (CHANGELOG 0.37.0 names the measurement). Keeping the
  * run whole also makes the "closing run at least as long as the opening
  * one" rule above literal: an opener longer than any closing run in the
  * input is no fence at all, where splitting the run instead matched it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrator-workflow",
-  "version": "0.39.0",
+  "version": "0.40.1",
   "description": "Installer for an orchestrator-led agent workflow: .ai/ run state, an AGENTS.md policy section, and per-harness subagent definitions for Claude Code, OpenAI Codex, and opencode",
   "main": "dist/index.js",
   "type": "module",