Skip to content

Add AGENTS.md guidance for coding agents - #3099

Merged
antonwolfy merged 12 commits into
masterfrom
add-agents-md
Oct 30, 2026
Merged

antonwolfy merged 12 commits into
masterfrom
add-agents-md

Conversation

@antonwolfy

@antonwolfy antonwolfy commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

This PR adds AGENTS.md files with guidance for AI coding agents working on dpnp: a root file plus one per area (dpnp/, dpnp/tests/, dpnp/backend/, dpnp/tensor/, doc/, benchmarks/, .github/).

It supersedes #2775. The .github/copilot-instructions.md and .github/instructions/* files proposed there are not added, because Copilot reads AGENTS.md and they would only duplicate it.

How the content was built:

  • Rules from review history. The rules come from recurring human review comments on about 540 recent PRs, keeping themes raised in at least 3 PRs: changelog entries, devices without fp64 support, compute follows data, hidden host transfers, docstring house style, CuPy tests mirroring upstream, short comments, and more.
  • Every claim checked against the tree. Commands, paths, identifiers and conventions were verified against the repository, since an agent follows them literally. No line numbers are used, so the files don't go stale with every edit.
  • Rules first, generic advice left out. The root file starts with the rules and the verification commands, plus a table of which CI checks are required on master. Each nested file only adds what is specific to its directory.

The files are plain AGENTS.md, which Claude Code, GitHub Copilot, Codex and Cursor read natively, including nested files, so no tool-specific copies are added.

Known gaps:

  • Gemini CLI reads only GEMINI.md unless context.fileName in its settings includes AGENTS.md.
  • Claude Code (v2.1.277 or later) reads AGENTS.md only when there is no project CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it, and skips a nested AGENTS.md whose own directory has one. So the repository should not gain a CLAUDE.md. A personal ~/.claude/CLAUDE.md or a managed CLAUDE.md doesn't count and loads alongside AGENTS.md. Contributors who keep a CLAUDE.local.md need to set "Project instructions" to claude-md-and-agents-md. Before v2.1.281, some sessions, such as those on Amazon Bedrock or with telemetry disabled, read only CLAUDE.md.
  • GitHub Copilot gives the nearest AGENTS.md precedence, so review-critical rules are kept in the root file.

Checklist:

  • Have you provided a meaningful PR description?
  • Have you added a test, reproducer or referred to an issue with a reproducer?
  • Have you tested your changes locally for CPU and GPU devices?
  • Have you made sure that new changes do not introduce compiler warnings?
  • Have you checked performance impact of proposed changes?
  • Have you added documentation for your changes, if necessary?
  • Have you added your changes to the changelog?

Add a root AGENTS.md and per-directory guides for dpnp/, dpnp/tests/,
dpnp/backend/, dpnp/tensor/, doc/, benchmarks/ and .github/.

The rules come from recurring maintainer review comments, and every
command, path and identifier in them is checked against the tree.
@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

View rendered docs @ https://intelpython.github.io/dpnp/index.html

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Array API standard conformance tests for dpnp=0.22.0dev0=np2py314h8d9cdd5_13 ran successfully.
Passed: 1491
Failed: 0
Skipped: 6

-m "slow or not slow" now runs slow tests, "0" disables the test env
flags, and large-allocation tests skip on USMAllocationError.
@antonwolfy antonwolfy added this to the 0.21.0 release milestone Oct 14, 2026
@coveralls

coveralls commented Oct 14, 2026 •

Copy link
Copy Markdown
Collaborator

Coverage Status

coverage: 82.636%. remained the same — add-agents-md into master

antonwolfy and others added 3 commits October 15, 2026 12:33
doc/docstring_template.py is current again, dpnp/tensor no longer
mentions dpctl.tensor, and placeholder pages are marked :orphan:.
New extensions call build_dpnp_pybind11_ext instead of copying an
existing CMakeLists.txt, and request -fno-sycl-id-queries-fit-in-int
with its LARGE_RANGES option.
antonwolfy and others added 4 commits October 27, 2026 11:01
Update the required conda job's Python range, point the conda-forge row at
conda-build-test.yml, list the type_dispatch headers by name, name
_usmarray.pxd as a source of the generated headers, and add rules for
updating references after a removal, rename or version bump.

@ndgrigorian ndgrigorian left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Don't see a problem, LGTM

antonwolfy and others added 3 commits October 29, 2026 11:29
Point the SYCL pin rule at .github/sycl-build-deps.env, which holds the
pins since #3112, say which dispatch helpers binary functions use and
that true_divide.cpp has init_divide, that only .pyx files are globbed,
that vm builds empty under oneMath and that the array-api comment is
posted on non-fork PRs only. In the test guide, name the five replaced
assert functions, what test_umath enumerates, the node ID format the
skip lists match and the CI jobs that test an editable or in-place
tree, and use a Test<Name> placeholder.
Name the -DUSE_ONEMATH* definitions that stay in each extension, the
pin file's line format, when the array-api PR comment is posted, which
CI jobs the test command mirrors and how tests_perf/ is excluded, and
use the <category> placeholder in the export example.
@antonwolfy
antonwolfy merged commit eb7f704 into master Oct 30, 2026
115 of 116 checks passed
@antonwolfy
antonwolfy deleted the add-agents-md branch October 30, 2026 09:27
github-actions Bot added a commit that referenced this pull request Oct 30, 2026
This PR adds `AGENTS.md` files with guidance for AI coding agents
working on dpnp: a root file plus one per area (`dpnp/`, `dpnp/tests/`,
`dpnp/backend/`, `dpnp/tensor/`, `doc/`, `benchmarks/`, `.github/`).

It supersedes #2775. The `.github/copilot-instructions.md` and
`.github/instructions/*` files proposed there are not added, because
Copilot reads `AGENTS.md` and they would only duplicate it.

How the content was built:
- **Rules from review history.** The rules come from recurring human
review comments on about 540 recent PRs, keeping themes raised in at
least 3 PRs: changelog entries, devices without fp64 support, compute
follows data, hidden host transfers, docstring house style, CuPy tests
mirroring upstream, short comments, and more.
- **Every claim checked against the tree.** Commands, paths, identifiers
and conventions were verified against the repository, since an agent
follows them literally. No line numbers are used, so the files don't go
stale with every edit.
- **Rules first, generic advice left out.** The root file starts with
the rules and the verification commands, plus a table of which CI checks
are required on master. Each nested file only adds what is specific to
its directory.

The files are plain `AGENTS.md`, which Claude Code, GitHub Copilot,
Codex and Cursor read natively, including nested files, so no
tool-specific copies are added.

Known gaps:
- Gemini CLI reads only `GEMINI.md` unless `context.fileName` in its
settings includes `AGENTS.md`.
- Claude Code (v2.1.277 or later) reads `AGENTS.md` only when there is
no project `CLAUDE.md`, `.claude/CLAUDE.md` or `CLAUDE.local.md` in the
working directory or above it, and skips a nested `AGENTS.md` whose own
directory has one. So the repository should not gain a `CLAUDE.md`. A
personal `~/.claude/CLAUDE.md` or a managed `CLAUDE.md` doesn't count
and loads alongside `AGENTS.md`. Contributors who keep a
`CLAUDE.local.md` need to set "Project instructions" to
`claude-md-and-agents-md`. Before v2.1.281, some sessions, such as those
on Amazon Bedrock or with telemetry disabled, read only `CLAUDE.md`.
- GitHub Copilot gives the nearest `AGENTS.md` precedence, so
review-critical rules are kept in the root file. eb7f704
napetrov added a commit to intel/dokimi that referenced this pull request Oct 30, 2026
…s lists them (#297)

* feat(repo): replay grades record each credited hit; report --hits

A dokimi:review_replay grade kept only the ids of the threads it
credited (details.threads_hit), not which finding hit each one. To check
a hit, the evaluation of IntelPython/dpnp#3099 had to rerun the
location matching by hand next to gold.json and answer.txt, and that is
how it found credits by chance: a finding on the right lines about
something else. Separately, an answer whose findings JSON does not parse
is graded parse_error with every recall 0, but no summary showed it, so
an arm that makes answers harder to parse read as a recall loss.

- grade_replay adds details.matches: per credited pair, in threads_hit
  order, the thread (id, file, line, comment cut to 200 characters), the
  finding (its index, repository-relative file, line as matched,
  severity, message cut to 200) and their distance. The matching and
  the metrics are unchanged, so VERSION stays 1; the graders digest a
  batch is pinned to changes with the source as before.
- repo report --hits lists those pairs by task, arm, model and rep, two
  lines each (--json: records with task, arm, model, rep and cell),
  counts the cells graded before matches existed, and says so when the
  batch has no review_replay cell. The default report is unchanged.
- repo report counts, per row, the cells whose grade.json has
  parse_error, as a note under the row ("agent answer(s) whose findings
  JSON did not parse") and as parse_errors in --json.
- Contract §4.5 and §9, the grader docstring and a changelog fragment.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* docs(repo): say why the replay grader version stays 1 with details.matches

A field added to details that leaves every metric and pass as they were
does not bump VERSION; a reader tells such a grade by the field being
present.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* test(repo): report --hits and the parse-error count on unreadable grades

Covers a grade.json that is not JSON or not an object, details that is
not an object, non-object and textless entries in matches, metrics that
is not an object and a non-boolean parse_error.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): report --hits refuses a cell with no rep, as the table does

After #238, repo report refuses a result.json of the wrong shape with a
CellFileError naming it (exit 1). load_cells checks task, arm and model;
--hits also sorts by rep, which the table never reads, so a cell without
it stopped --hits with a KeyError traceback. load_hits now refuses it
the same way: "<cell>/result.json has no usable `rep`".

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* test(repo): pin "" for missing match text and rep order of --hits

Review comment 4416180649: test_replay_matches_record_each_credited_pair_
nearest_first now grades a thread with no `comment` against a finding
with no `severity` or `message` and compares the match with a literal
whose three fields are "". Before, every input supplied those strings,
so `_cut` could turn None into "None" and the suite still passed.

Review comment 4416180698: test_hits_list_each_credited_pair_by_task_
arm_and_rep adds a replay cell with rep 10 next to rep 2. By directory
name r10 sorts before r2, so the expected listing, rep 1, 2, then 10,
now fails if load_hits drops its (task, arm, model, rep) sort or sorts
the rep as a string.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): report reads grade.json as the host does; --hits skips grader failures

`repo report` reads every cell's grade.json for parse_errors, and --hits
for the matches. _grade_doc read it with a plain read_text, so a FIFO
blocked the whole table, a link out of the batch was followed, and a
deeply nested file raised RecursionError. It now goes through
grading.read_grade_json, the reader read_grade uses (lstat, O_NOFOLLOW,
and RecursionError as no grade). read_grade gets the RecursionError
case too: it used to crash the grading of such a cell.

--hits also credits no match of a cell whose result says grader_failure,
which the table scores as 0.

Signed-off-by: Nikolay Petrov <nikolay.a.petrov@intel.com>

* fix(repo): parse_errors skips grader failures; score rows say scored 0

Review comment 4418950465 (the parse_errors half): a cell whose
result.json says grader_failure was counted both in the row's
grader_failures and, when its grade.json had metrics.parse_error, in
parse_errors. summarize now leaves it out of parse_errors, as 9092ed4
leaves it out of --hits.

Review comment 4418950480: the parse-error note said "(counted as
failed)" on every row, but a score-only row (every
dokimi:review_replay row) has no failure count; the cell is in the mean
as a score of 0. The note now says "(scored 0)" on a score row and keeps
"(counted as failed)" on a gate row.

The module docstring, contract §9 and the changelog fragment say both.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* docs(cli): repo report --hits help says by task, arm, model and rep

Review comment 4418950473: the --hits help said the pairs are listed
"by task, arm and rep", but load_hits sorts and format_hits groups them
by task, arm, model and rep, as contract §9 and the changelog fragment
already say. The help now says so too.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* test(repo): FIFO grade test skips without mkfifo and fails on a block

Review comment 4420760178: the test called os.mkfifo unguarded, an
AttributeError on Windows. It is now skipped where os.mkfifo is missing,
as tests/test_task_format_detect.py does.

Review comment 4420760207: a report that opened the FIFO could still
pass, because the cleanup opened the write end, the blocked read got EOF
and the empty file read as no grade. The test now records whether the
first join timed out, then opens the write end (non-blocking, a bounded
number of times) until every blocked read has ended, and only then
asserts that it did not time out.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* test(cli): allowlist repo report --hits and refresh the CLI snapshot

The merge with main brings the flag registry of #254: its ratchet test
fails a spelling that is neither canonical in dokimi/cli_flags.py nor on
tests/data/cli_flags_allowlist.txt, and CI fails a stale
docs/reference/cli-interface.json. `--hits` switches repo report from the
table to the list of credited replay hits; no registry concept names a
view switch, so it gets an allowlist row with that reason, and the
snapshot is regenerated with what `make cli-snapshot` runs (the only
change is the --hits option).

#298's scripts/check_comment_blocks.py --base origin/main --head HEAD
finds no comment block over two lines among the lines this PR adds or
edits, so no comment changes.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): repo report --hits keeps the cell's key over a match's

Review comment 4422546939: load_hits built each hit as the cell's task,
arm, model, rep and cell followed by **match, so a details.matches entry
with a key of one of those names moved the hit to another task or
repetition in both --hits and --hits --json. The match is now spread
first and the result.json values last. format_hits only reads these
records, so it needs no change.

A new test grades a cell whose match carries all five colliding keys and
checks that the JSON records and the text listing show the cell's own
task, arm, model, rep and cell. The contract (§9) and the changelog
fragment say the five come from result.json.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

---------

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>
Signed-off-by: Nikolay Petrov <nikolay.a.petrov@intel.com>
Co-authored-by: Nikolay Petrov <nikolay.a.petrov@intel.com>
antonwolfy added a commit to intel/dokimi that referenced this pull request Oct 30, 2026
Found while evaluating IntelPython/dpnp#3099 (AGENTS.md guidance): at dpnp
0cf6730, dpnp/tensor/AGENTS.md:9 names `type_dispatch*.hpp` and
`type_utils.hpp` on one line. The bare name was `ok_basename`; the glob was
`unresolved` ("matches nothing in the tree; a build may create it"), though
it matches three files in two directories.

Scan._glob tried a glob only at the guidance file's directory and its
ancestors; for a glob with no `/` nothing ran after that, while
resolve_path looks a bare name up among the basenames of the tree. A glob
with no `/` that matches nothing at those bases is now matched against the
same basenames (Scan._bare_glob): `ok_basename`, with the number of matches
and of directories they lie in. With no match the claim is unchanged,
reason and .gitignore check included. The contract (section 8) and the
module docstring say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>
antonwolfy added a commit to intel/dokimi that referenced this pull request Nov 3, 2026
…kens (#368)

* fix(repo): reach prose count skips a lead-in line before the tokens

A `repo reach` audit on IntelPython/dpnp#3099 had Haiku answer the
read=dpnp scenario with "Now I'll list all verification tokens found in
my context:" on its own line and then all four tokens. prose_words
counted the lead-in's 10 words and the text output warned "answered with
10 words besides tokens; read its trace before trusting its not_loaded
cells", though every token was reported.

prose_words now drops the first non-empty line when it ends in ':' and a
later line holds a token. Every other word still counts: a sentence after
the tokens, a lead-in with no token after it, a first line that does not
end in ':'. Contract section 7's `prose` bullet says so; the cases are
pinned in tests/test_repo_reach_edges.py next to the other prose tests.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach prose skips only a short lead-in line

Review of #368: the lead-in was dropped whatever its length, so a
one-line explanation or partial refusal ending in ':' before a token
counted as 0 prose and the warning to check that trace's not_loaded
cells stayed silent.

prose_words now skips the first non-empty line only when it ends in
':', has at most LEAD_IN_WORDS (12) words and a later line holds a
token; Haiku's lead-in has 10. A longer line counts. The tests add the
reviewer's 23-word refusal line (counted) and a 12/13-word boundary
pair; the docstring, the contract's prose bullet and the changelog
fragment state the limit.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

---------

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>
antonwolfy added a commit to intel/dokimi that referenced this pull request Nov 3, 2026
…366)

* fix(repo): budget turns off an AGENTS.md beside its own CLAUDE* file

Settles item 5 of the follow-ups from the dokimi review of
IntelPython/dpnp#3099: `repo budget` modelled only a root CLAUDE.md,
.claude/CLAUDE.md or CLAUDE.local.md turning AGENTS.md off. Claude Code
2.1.316 also skips a subdirectory's AGENTS.md when that same directory
holds its own CLAUDE.md, CLAUDE.local.md or .claude/CLAUDE.md, also when
the agent reaches the directory lazily from the root; budget counted
that AGENTS.md, and its imports, as lazy.

A new helper, _displaced, decides which AGENTS.md files a CLAUDE* file
turns off: every one while a root CLAUDE* resolves (unchanged), else a
nested one whose own directory holds a resolvable CLAUDE* file. One in a
parent or deeper directory does not count. The existing exceptions
apply: a CLAUDE* alias of the file, or an import from a loaded file,
keeps it lazy, and so does the same file reached as an AGENTS.md in a
directory with no CLAUDE*. A displaced nested AGENTS.md adds no imports
of its own. The off warning names the CLAUDE* file for each nested one.

The claude-code profile notes, the module docstring, `repo budget
--help`, the repo evaluation contract and architecture.md describe the
nested rule. budget() drops one branch to _off_warnings, so its growth
baseline shrinks from 21 to 20.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): only claude-code's budget turns off an AGENTS.md by its CLAUDE*

Review of #366 (comments 4445841674, 4446226790): the same-directory rule
keyed on any CLAUDE* name in the profile's guidance names, and copilot.yaml
and copilot-review.yaml list CLAUDE.md. A Copilot budget of a tree with
AGENTS.md, sub/AGENTS.md and sub/CLAUDE.md reported sub/AGENTS.md off 7,
with a Claude Code warning, where main reported it lazy, while the
changelog says Copilot gets the same budget as before.

The rule is now gated on a profile flag, guidance.claude_displaces_agents,
an optional boolean added in place to harness_profile.v1 and set only in
claude-code.yaml. budget() takes it as the keyword claude_displaces_agents
(default false) and both repo budget and the reach receipt pass the
profile's value. The root rule is unchanged. Tests run repo budget
--harness copilot and copilot-review on the reviewer's tree (lazy) and
--harness claude-code on it (off).

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): budget leaves .claude/AGENTS.md to the root rule

Review of #366 (comments 4445841688, 4446226802): _is_root treats
.claude/AGENTS.md as a root file, read at start, but _displaced treated it
as nested, so .claude/CLAUDE.local.md or .claude/.claude/CLAUDE.md beside it
turned it from start 5 (main) to off, with a new warning. The comment "at
the root a CLAUDE* would have taken the branch above" did not hold for it.

_displaced now skips every file _is_root accepts: only a root CLAUDE*
turns AGENTS.md or .claude/AGENTS.md off. A test pins the tree with only
.claude/AGENTS.md and .claude/CLAUDE.local.md (or .claude/.claude/CLAUDE.md)
at start, with nothing off and no warning.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* docs(repo): keep the root rule in claude-code's AGENTS.md notes

Review of #366 (comment 4445841700): the notes said a CLAUDE* in a parent
directory does not turn a lazily reached AGENTS.md off, while budget turns
every AGENTS.md off under a root CLAUDE.md, the root being a parent of
every directory. The dropped sentence about one CLAUDE.md turning
AGENTS.md off for the whole session was what explained it.

Both cases were measured on Claude Code 2.1.316 (Haiku 4.5), with and
without a root CLAUDE*. guidance.notes now say a CLAUDE* in a parent below
the root does not turn the AGENTS.md off, and a root CLAUDE* file
(CLAUDE.local.md included) turns every AGENTS.md off for the whole
session. The contract, docs/architecture.md, the budget.py docstring and
the changelog fragment say "a parent below the root" too. No code change.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* refactor(repo): one CLAUDE* set for budget's nested rule and the receipt

Review of #366 (comment 4445841710): _displaced spelled out CLAUDE.md,
CLAUDE.local.md and .claude/CLAUDE.md again, beside receipt.CLAUDE_ROOT,
so a location added to one could miss the other.

CLAUDE_ROOT moves to budget.py, which receipt.py already imports (budget
imports nothing from receipt, so no cycle), and _displaced builds the
names beside an AGENTS.md from it. A test checks that the receipt reads the
same object and that the nested rule follows the constant.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): budget does not turn off a nested AGENTS.md that dangles

Settles the review point that a nested sub/AGENTS.md which is a broken
link, beside a real sub/CLAUDE.md, came out `off` with the warning that
Claude Code does not read it, on top of the not-readable warning, while
the base budget gave it `lazy` with the not-readable warning only.

_displaced now applies the same-directory CLAUDE* rule only to an
AGENTS.md that resolves (_is_resolvable): a dangling or out-of-tree link
keeps the status and the single warning the base gives it. A readable
AGENTS.md beside a CLAUDE* file is still `off`. The root rule is
unchanged. The module docstring, the contract and the changelog fragment
say "that resolves".

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

---------

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>
antonwolfy added a commit to intel/dokimi that referenced this pull request Nov 3, 2026
* feat(repo): reach --scenarios shadow adds a CLAUDE.local.md

Follow-up to the dokimi review of IntelPython/dpnp#3099 (item 4). repo reach
probed the tree as it is, so on a tree with AGENTS.md files and no CLAUDE*
file it could not show that a CLAUDE* file turns them off, although
budget.py's `off` bullet said the reach probe re-measures that rule.

- Harness profiles take an optional guidance.shadow_file (harness_profile.v1
  widened in place); the claude-code profile sets it to CLAUDE.local.md.
- A new --scenarios kind, shadow, outside the default root,cwd,read:
  shadow=. writes the shadow file at the root and runs as cwd=.;
  shadow=<dir> writes it in each guidance directory holding a file not named
  CLAUDE* and runs as read=<dir>. A directory where the tree already has a
  file at that path is skipped. The file is seeded with its own tokens
  (distinct_salt counts them), never committed, and removed when its
  scenario ends, after an error too.
- Its result is a `shadow` record on the scenario row (guidance_reach.v1
  widened in place) and one line under the matrix; the matrix keeps one row
  per tree file. --dry-run lists the shadow scenarios with their file.
- A profile without guidance.shadow_file refuses the kind (exit 2). The
  --scenarios help names the default instead of "all".
- Contract sections 6 and 7 say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach shadow skips blocked paths, refuses probe-file parents

Settles two review points on the reach shadow scenarios.

A shadow path was free when no tree file sat at it or under it. It is
now also taken when a tree file sits above it (AGENTS.md for a shadow
file AGENTS.md/local.md) and when the tree holds a directory at it,
which the file list leaves out when the directory is empty: Shadow asks
the tree (RepoTree.is_dir) once per candidate path, and a path the tree
cannot resolve counts as taken.

In the workspace, a shadow path that would go under one of the probe's
own entries that is not a directory (a REACH_PROBE.txt, a seeded file,
a link) is refused with a ReachError before anything is written, as a
path that would replace one already was. The cleanup removes only what
the call made: the file once its write has begun, and the outermost
directory it created. An OSError while creating becomes a ReachError
naming the path, after that cleanup, so `repo reach` reports it as
`✗ ...` with exit 1 instead of a traceback.

The contract's §7 and the changelog fragment say what the skip covers.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach shadow treats a looping ignored link as taken

Settles review comment 4443412079 on #367. A git working tree can hold
an ignored CLAUDE.local.md that is a link to itself: it is in no file
list, so Shadow.free asks WorkTree.is_dir, and Path.resolve raises
RuntimeError on the loop before Python 3.13. That escaped as a
traceback from `repo reach --scenarios shadow`, --dry-run included.
Shadow.free now counts RuntimeError and OSError, the failures
WorkTree.resolve already maps, as taken, as it does a SourceError.
WorkTree.is_dir is unchanged for its other callers. On Python 3.13+
resolve does not raise for the loop, so the link reads as an ignored
non-directory, which the skeleton workspace never holds.

The tests use a real ignored looping link in a git working tree, for
the scenario list and for the --dry-run command, each also with
Path.resolve raising RuntimeError on the loop as before Python 3.13;
and a tree whose is_dir raises each of the three errors.

Comment 4443412060 needs no code change. The contract's skip line now
says what the code compares: the tree's files ignoring case, an empty
directory by the disk's own lookup.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach receipt leaves the shadow scenarios out

Review of #367 (comment 4445805701): `repo reach --format receipt`
built one receipt per scenario row and did not know about a row's
`shadow` record. A `shadow=.` receipt therefore described the tree as
committed while the run had a CLAUDE.local.md the tree lacks, and said
`AGENTS.md: expected true, observed not_loaded` with the shadow file
in none of its sources.

build_receipt now skips a row that carries a `shadow` record, for a
live run and for `--from` alike: the receipt describes the tree as
committed, and the shadow results stay in reach.json and the matrix.
Contract §7.1 and the changelog fragment say so; a test runs
`root,shadow` and gets a receipt with the `cwd=.` row only.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach checks shadow paths before any scenario runs

Review of #367 (comments 4445805709 and 4446227108): a shadow path that
went under or over a probe file (`shadow_file: REACH_PROBE.txt/x.md`)
was refused only when its own scenario started. With
`--scenarios root,cwd,read,shadow` the harness ran three times, and
was billed for them, before the ReachError, and no reach.json was
saved.

The workspace is the same in every scenario, so run_reach now checks
every planned shadow path once, right after build_workspace and before
the harness's version command or any scenario (_check_shadow_paths).
_shadowed keeps its own check. Contract §7 and the changelog fragment
say when the refusal comes; a test with a harness that counts its
calls gets the ReachError after none.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach --dry-run plans from the files a run probes

Review of #367 (comment 4446227118): `repo reach --dry-run` and the
`--only` check planned from probe_files(), before run_reach drops the
links it cannot follow. With `sub/AGENTS.md -> nowhere.md`, the dry run
listed `cwd=sub`, `read=sub` and `shadow=sub`, which a run never
executes: it lists the link under `unresolved` and probes nothing in
`sub/`.

followable() in repos/reach.py returns the probed files without those
links, with resolve_links's groups and unresolved list. run_reach and
the command both plan from it, so the dry run, the `--only` check and
the scenario count match the run for every kind. The dry run's `files`
key still lists every probed path. A test plants the dangling link: the
dry run lists `cwd=.` and `shadow=.` only, and `--only read=sub` is a
usage error. Changelog fragment, category Fixed.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach --dry-run refuses a tree of unfollowable links

Settles a review point on the reach shadow kind: with only
`AGENTS.md -> nowhere.md` as guidance, `repo reach --dry-run` (with
`--scenarios shadow --only shadow=.`, or the default `cwd=.`) listed a
scenario and exited 0, while a run stopped at run_reach's
"no guidance file to probe" guard with exit 1.

followable() now holds that guard, so run_reach and the command share
it. The command's planning moves into _reach_plan, which calls
followable() before the dry run, the --only check and the scenario
count, and exits 1 on that refusal as a run does.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach --dry-run refuses what a run refuses

Settles review comment 4447141458 on #367: with every shadow
path already in the tree (AGENTS.md, CLAUDE.local.md, sub/AGENTS.md,
sub/CLAUDE.local.md and --scenarios shadow), `repo reach --dry-run`
printed `"runs": []` and exited 0, while the run exited 2 with "no
scenario selected". _reach_plan returned from its --dry-run branch before
the count check.

The dry run now goes through the same path as a run up to its first
harness call. _reach_plan makes the count check in both modes, the
command makes its receipt-over-probe check before the dry run, and
run_reach takes dry_run: it builds the workspace (now in _prepare, shared
with the run), makes the checks of the build, removes the workspace and
returns the files and the planned runs before the harness's version
command. That also closes the other gaps a look over the run's refusals
found, each of which the dry run printed a plan for and exited 0: a
receipt that would replace the probe (2), a tree with no guidance file, a
guidance file above the workspace, a guidance file that is not UTF-8, a
tree path the workspace cannot hold, and a shadow path under a probe file
(1). Contract §7, the --dry-run help and the dry-run changelog fragment
say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach reports a --work-dir it cannot use, not a traceback

Settles review comment 4447340550 on the reach shadow follow-up: a
--work-dir that is missing, not a directory or not writable made
tempfile.mkdtemp raise FileNotFoundError, NotADirectoryError or
PermissionError, which neither run_reach nor the command caught, so a
dry run and a run alike ended in a traceback.

run_reach now makes its directory in _make_base, which turns that
OSError into a ReachError naming the directory; the command's existing
handler prints it as a single error line with exit 1. The same applies
to a write the workspace refuses while _prepare builds it (a full
disk): "cannot build the probe workspace <dir>: <reason>". _prepare
picks the salt before it builds, since that step reads only the tree,
so a tree read is not reported as a workspace failure. The out-dir
check already caught OSError, and removing the workspace ignores
failures, so neither needed a change.

Tests cover a missing, file-valued and unwritable (mkdtemp patched to
raise PermissionError) --work-dir and a full disk while seeding, each
in both modes; the contract's dry-run paragraph and the changelog
fragment say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach guards the shadow file's name above the workspace

Settles review comment 4447531771 on the reach shadow follow-up: the
check for guidance files above the workspace looked for the built-in
names and the profile's guidance.names only. A custom profile with
guidance.names [AGENTS.md] and guidance.shadow_file MEMORY.md, run with
a --work-dir that holds a MEMORY.md, passed that check, though a harness
that loads MEMORY.md by convention would read the one above the
workspace in every scenario.

_prepare now takes the names from _guarded: when a shadow scenario is
planned, the file name (last path part) of each planned shadow path,
which shadow_for has already checked, joins ANCESTOR_GUARD and the
profile's guidance names. The default CLAUDE.local.md was in
ANCESTOR_GUARD already. Without a shadow scenario the names are
unchanged. A run and a dry run share _prepare, so both refuse alike.

Tests: MEMORY.md, .memory/MEMORY.md and CLAUDE.local.md as shadow files,
each with its name in the --work-dir, give the same refusal and exit 1
in a dry run and a run, with no harness call; without a shadow scenario
the dry run plans as before. The contract's ancestor-guard line and the
changelog fragment say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach guards the shadow file's path above the workspace

Settles the review point that the ancestor guard kept only the last part
of guidance.shadow_file. For `shadow_file: .claude/CLAUDE.local.md` it
looked for `<ancestor>/CLAUDE.local.md` and missed
`<ancestor>/.claude/CLAUDE.local.md`, which the harness then loads in
every scenario; for `shadow_file: .claude/MEM.md` a plain `MEM.md`
above --work-dir, which that profile never loads, stopped the run.

_guarded now adds profile.shadow_file as given, a relative path that
shadow_for has already checked, when a shadow scenario is planned;
check_ancestors already takes such paths (`.claude/CLAUDE.md`). Without
a shadow scenario the guard is unchanged. Contract §7 says "the path as
given" instead of "last path part", and the changelog fragment says so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* test(repo): reach work-dir refusal takes the OS's own reason

Settles the review point that
test_repo_reach_with_a_work_dir_it_cannot_use_fails_cleanly_in_both_modes
failed on Windows for a missing --work-dir and for one that is a file:
it expected the POSIX texts "No such file or directory" and "Not a
directory", where Windows says "The system cannot find the path
specified". The code already printed a clean line there.

The test now builds the reason as the code does, from the OSError that
mkdtemp raises in that directory on this OS (strerror, else the
exception), and still asserts the whole line, the
"cannot make the probe workspace in --work-dir <dir>: " prefix
included, and exit 1, in a dry run and a run alike.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach names a tree with no guidance file before selection

Settles the review-body point that, on a tree with no guidance file, a
run and a dry run with `--scenarios cwd` exited 2 with
`no scenario selected`: the selection check in the command ran before
run_reach's own check for a file to probe, so the message named the
wrong cause.

The check moves to reach.check_files, which run_reach and the
command's _reach_plan both call; _reach_plan calls it right after
probe_files, before the scenarios are selected, beside the followable
guard and with its exit code. Such a tree now stops with
`no guidance files to probe` and exit 1 in both modes, as a run with
the default scenarios does on main. Changelog fragment: one entry.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

---------

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>
antonwolfy added a commit to intel/dokimi that referenced this pull request Nov 4, 2026
#369)

* fix(repo): Claude Code Bash reads count as reads; bash= reach scenario

Settles two points of an audit of a `dokimi repo run` replay on
IntelPython/dpnp#3099.

Item 6: under Claude Code, guidance_read counted the Read tool only. In
the replay 17 of 78 guidance cells printed an AGENTS.md with Bash
(`cd benchmarks; cat AGENTS.md`) and all had guidance_read []. The
claude-stream-json converter now runs cli_traces.shell_reads on each
Bash command, as the Codex and Copilot readers do since #116, and emits
a read event per printed file before the command event (same t, the
subagent's agent id). Claude Code keeps the shell's directory between
calls, so after an agent's call that ran a cd or pushd
(shell_reads_moved), its later relative reads are skipped and absolute
ones kept. On the tool_result, a hook or permission denial marks the
reads denied, an is_error result of a one-file, one-part read drops it
(cli_traces._failed_read), and otherwise the reads get rc 0. The new
logic sits in helpers, so events._apply drops from complexity 17 to 14.
process_metrics is unchanged; the contract (4.1, 6, 7, 7.1) and the
module docstrings say which shell reads count, now for all three
harnesses.

Item 7: no reach scenario measured whether a Bash read of a nested file
loads its directory's guidance. `repo reach --scenarios bash` adds
bash=<dir>, started at the root with the profile's new `bash` tool mode
(claude-code: --tools Bash), telling the agent to
`cat <dir>/REACH_PROBE.txt`. The default kinds stay root,cwd,read. A
profile without a bash mode (codex, copilot) is a usage error, exit 2.
harness_profile.v1 accepts the optional `tools.bash` key in place; it
is left out of delegation.none, whose propertyNames schema_compat holds
fixed. The receipt maps bash=<dir> as it maps read=<dir>.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a cd in a job or pipeline does not move the Bash shell

Review of #369 (comments 4443237154, 4443248498): shell_reads_moved()
returned the walker's chain flag `moved`, which says a cd was seen, not
that the shell the script runs in may have moved. `cd sub &`,
`{ cd sub; } | cat`, `{ cd sub; } &` and `cd sub && make &` all came back
as moved, so a later Bash call's `cat AGENTS.md` of the same agent lost
its root read.

_Walk now keeps `shell_moved` apart from `moved`: a cd, pushd or popd
sets it only outside a subshell, and it is saved with the directory at
the start of an && / || list and at a brace group's opening, and
restored wherever the directory is (a backgrounded list, a piped or
backgrounded group, and a list backgrounded at the end of the script).
`moved` and the reads of Codex and Copilot commands are unchanged.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): settle Claude Code Bash reads once the trace ends

Review of #369 (comments 4443237165, 4443237182). Two orders of the
stream-json trace gave wrong reads:

- A permission refusal can come back as an `is_error` tool_result
  (`Permission to use Bash has been denied`) and only later as a
  `permission_denials` entry in the final result. The error result
  dropped the read of a one-file `cat AGENTS.md`, so the denial marked a
  detached event: the trace lost the denied read and `tool_calls` was
  one short.
- A call's `cd` marked the agent's shell as moved at tool_use time, so a
  `cd sub` that a PreToolUse hook or the permissions refused still cost
  the next call's `cat AGENTS.md` its read.

The converter now records each Bash call (its agent, order, named
paths, whether it moves the shell, and ok / error / denied) and settles
them all after the last line: a denied call moves nothing and keeps its
reads, denied; a failed one-file read drops its read; after a call that
was not denied and may have moved the shell, only absolute reads are
kept; otherwise reads get rc 0. Read events are still inserted before
their command event at tool_use time, and only the dropped ones are
removed at the end, so every read keeps its place. events._apply stays
at complexity 14.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a refused or failed read is no read in reach or skill use

Review of #369 (comment 4443248578): Transcript.reads(), which reach's
classify and so the receipt's `read_by_tool` use, and arms.skill_usage
took every read event, including denied ones and failed ones (rc 1). A
refused `cat sub/AGENTS.md` made an already-loaded file `fetched` and its
receipt `states.accessed` true, and a refused read of an installed
SKILL.md counted the skill as used. The Read tool had the same bug
before the Bash reads of this PR.

Both now take only reads that showed the file (transcript.shown_read:
not denied, rc 0 or no result), as process_metrics' guidance_read
already did. The events stay in events.jsonl for audit.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): shell-quote the probe path in the bash= reach prompt

Review of #369 (comments 4443237195, 4443248319): the bash= prompt put
the probe path into the Bash command as it was. Repository directory
names keep spaces and shell metacharacters, so guidance in
`my package/AGENTS.md` asked for `cat my package/REACH_PROBE.txt`,
which reads `my` and `package/REACH_PROBE.txt`, and a `$` or `;` in the
name changed what the command does.

The operand is now reach.shell_word(path): shlex.quote of the path,
with `./` in front of a path that starts with `-`. Scenario.read keeps
the raw path, and the Read-tool prompt is unchanged. The fake harness
of test_repo_reach_bash.py parses the quoted operand with shlex.split
and runs the command as the prompt names it.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* test(repo): POSIX paths in the fake Bash commands of the bash= tests

Review of #369 (comment 4443248422): the fake harness of
test_repo_reach_bash.py built its Bash commands from str(Path). On
Windows that gives `cat sub\AGENTS.md`, which the POSIX shell parser
reads as `subAGENTS.md`, so the read-event and fetched assertions
would fail there.

The probe command is the prompt's own operand (since the quoting fix),
and the command that cats the directory's AGENTS.md is built with
as_posix() and shell-quoted. Test-only change.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a brace group's separators do not end the list around it

`cd sub && { echo a; echo b; } &` backgrounds the whole && list, so the
shell does not move, yet shell_reads_moved returned moved=True: the `;`
inside the group overwrote the saved start of the enclosing list
(`list_start` / `listed`), and the final `&` restored the state after
`cd sub` instead of the state before it. A following Claude Code Bash
`cat AGENTS.md` then lost its root read.

A brace group now saves the enclosing list's state when it opens and
restores it when it closes, so the group is one command of that list.
`cd sub && { cd x; cat a; } &` moves nothing either, while
`cd sub && { echo a; }` (not backgrounded) still moves. The same fix
makes `cd x && { cat f; cat h; } & cat g` read `g`, not `x/g`.

Settles review comment 4443584029 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a computed cd in a job or a pipeline moves no Bash shell

`cd "$X" &` and `cd sub | cat` run their `cd` in a subshell, yet
shell_reads_moved returned moved=True: a computed part (an expansion, a
pipe or a redirect) is not split into words, and `_Walk.words` called
`lose()` for its `cd` without knowing the part was backgrounded or piped.
A following Claude Code Bash `cat AGENTS.md` then lost its read.

`words` now takes the part's operator after it; for a backgrounded part
or a pipeline (an unquoted, unescaped `|`), `lose()` still drops the
directory for the rest of the script but does not mark the shell moved.
`cd "$X" &`, `cd "$X" | cat`, `cd sub | cat` and `echo | cd sub` move
nothing; `cd "$X"`, `cd "$X" && make`, `cd $(pwd)` and `cd a\|b` still
move.

Settles review comment 4443584037 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): one moved Bash shell for the parent and its subagents

The Claude Code converter kept the "shell may have moved" state per
agent: after the parent ran `cd sub`, a subagent's `cat AGENTS.md`
still gave a read of the root AGENTS.md (and the reverse). Claude Code
keeps the Bash directory as process state, and a Task subagent may well
share it, so such a read may name a file the agent was never shown.

`_settle_bash` now keeps one flag for the whole trace: once any
non-denied call may have moved the shell, every agent's later relative
reads are dropped, absolute ones kept. This only drops reads, so it is
safe whether subagents share the parent's shell or not. The per-agent
field of `_BashCall` goes. The test that pinned the per-agent model is
replaced by one test per direction (parent cd, then a subagent's read;
subagent cd, then the parent's). The contract's guidance_read row, the
`fetched` bullet and the "cannot show" list say so.

Settles review comment 4445790393 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a refused Skill call is no use of the skill

arms.skill_usage skipped a refused or failed SKILL.md read, but its
`Skill` branch had no such check: a Skill tool call that a hook or the
permissions refused (`denied`) still put the skill in `skills_used` and
made `skill_invoked` true, though the skill never ran.

The loop now skips a denied or failed event (`rc` not 0 or None) at the
top, before either branch. The same class of bug was in
uptake.arm_uptake: it skipped denied events, but a read of a file a
`patch:` arm added that failed (`rc` 1, no such file) still counted in
`uptake.reads`; it now takes only reads that showed the file
(transcript.shown_read). Tests: a hook-denied and a permission-denied
Skill call, and a failed read of an added file. The contract's
skills_used and uptake text say so.

Settles review comment 4445790411 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a failed cd-then-read command is no read

`_failed_read` dropped the read of a failed command only when the
command was one part. `cd sub && cat AGENTS.md` with no sub/AGENTS.md
exits 1, yet its read of sub/AGENTS.md stayed with `rc` 0, so
guidance_read, skills_used and reach's `fetched` counted a file the
agent never saw.

A one-file read after `cd` parts now counts as one read part: a
non-zero exit means the read did not run (`cd sub && cat f`, the cd
failed) or ran and failed (the exit after `;`, `&` or `||` is the
read's), and either way the file was not shown. A list whose other part
is not a `cd` (`make && cat f`, `cat f && cd sub`) keeps its read, as
the exit does not say which part failed. The rule is shared, so a Codex
or Copilot command gets the same fix. Tests: the reviewer's probe and
five more cd forms, three lists that keep their read, and a Copilot
row. The contract's guidance_read row and `fetched` bullet say so.

Settles review comment 4446227568 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a refused Bash read after a cd stays, denied

After a `cd sub` that ran, a hook-refused `cat AGENTS.md` lost its read
event: `_settle_bash` checked "the shell may have moved, so a relative
read is not known" before it checked the denial, and dropped the read.
Only the command event was left, so `tool_calls` was one short, and the
module docstring's promise that a refused call's reads stay, `denied`,
did not hold.

The denial is now checked first. A refused call ran nothing, so its
reads stay, `denied`, after a move too; a relative path is then taken
from the start directory, and guidance_read, reach and skill use skip
a denied read anyway. Test: a `cd sub`, then a `cat AGENTS.md` refused
by a hook or by `permission_denials`, keeps the denied read, counts 3
tool calls and gives no guidance_read.

Settles review comment 4446227577 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): eval, source and time cd move the Bash shell too

`shell_reads_moved` did not set `moved` for `eval "cd sub"`,
`source env.sh` or `time cd sub`, so after such a Claude Code Bash call a
later relative `cat AGENTS.md` was still recorded as a read of the root
AGENTS.md, though the shell may be elsewhere.

`eval`, `source` and `.` now lose the directory as `pushd` / `popd` do:
they may run a `cd` that is not seen, so the shell may have moved (and
within one call, a relative read after them is not recorded). `time`
before a directory builtin is skipped like `builtin` and `command`, so
`time cd sub` is a `cd` (`command cd sub` already was). The parser is
shared, so a Codex or Copilot command follows the same rule within the
command. A `cd` in a shell function defined and then called is still not
seen; the contract's "cannot show" list says so, and its guidance_read
row and `fetched` bullet name the new forms. Tests: each form's `moved`,
a later call's relative read, and reads within the call.

Settles review comment 4446227585 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* docs(repo): tool_calls counts kept shell reads, denied ones too

The contract's tool_calls row and the process_metrics docstring said
it counts the read event of each file a shell command printed. It
counts every event: a refused `cat AGENTS.md` keeps a denied read, and
a failed `cat AGENTS.md missing.md` keeps a read for both paths, since
the exit code does not say which file failed. Say so, so the count is
not taken for evidence that a file was shown.

Settles review comment 4446703136 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a failed Skill call is no use of the skill

skill_usage skips an event with a non-zero rc, but the Claude Code
converter set rc on read and command events only. A Skill call whose
tool_result is an error ("Skill lint could not be loaded") with no hook
refusal or permission denial stayed a plain tool event, so the skill
counted as used, invoked and correctly selected.

_apply_result now sets rc (0, or 1 on an error) on a Skill tool event as
it does on a read. No other consumer reads rc on a tool event (uptake's
mcp_calls, tool_calls, reach and the consistency check do not), so only
skill usage changes. A permission-denied Skill call now carries rc 1 next
to denied, as a permission-denied command does.

Settles review comment 4446703155 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a cd $(...) in a pipeline moves no Bash shell

A part holding a command substitution goes down the walker's subshell
branch, which marked the shell moved unless the part was backgrounded.
So `cd $(pwd) | cat` set shell_moved although the cd ran in a pipeline
stage, and the next Claude Code Bash call's `cat AGENTS.md` lost its
relative read.

Both branches that see a directory builtin with a computed operand now
ask one helper, _in_own_shell, whether the part runs in the script's
shell: not backgrounded, and holding no pipe outside quotes, escapes,
$( ... ) and backticks (so `cd $(echo a | tr a b)` still moves). The
computed-word branch of _Walk.words reuses _runs_dir_before_parens for
its builtin test, which is the same test on a part without parentheses.

Settles review comment 4446703160 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a failed time cd-then-read command is no read

_failed_read drops the read of a failed command that is one read of one
file after cd parts, but took a part for a cd only when its first word
was `cd`. The shell walker also runs a cd after `time`, `command`,
`builtin` or a NAME=value word, so a failing `time cd sub && cat
AGENTS.md` kept its sub/AGENTS.md read at rc 0, and guidance, skill use,
reach access and uptake counted a file that was never shown.

The test now goes through _command_words, the walker's own helper, so
the two agree: `time cd`, `command cd`, `builtin cd` and `X=1 cd` are a
cd, and `env cd` (no builtin runs) is not, as before. The helper is
shared by the Codex and Copilot readers too.

Settles review comment 4446703173 on #369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): follow a brace group past the $( ) and groups in it

Settles the review point that `{ cd $(pwd); } | cat` and
`{ cd $(pwd); } &` moved the Bash shell: the part holding `$( )` was
skipped as a subshell before its `{` was seen, so the group's pipe or
`&` had nothing to restore, and a later relative `cat AGENTS.md` was
dropped.

The splitter now gives each part its outer text, the text outside any
`( ... )` or backticks. The walker tracks brace groups on that text
before it skips a subshell part, and tells a `cd $(...)` by it. So:

- a group whose first command holds `$( )` or backticks, or whose
  closing part does (`{ cd sub; } | grep $(x)`), opens and closes as
  any group;
- a `cd` inside `$( )`, backticks or `( ... )` moves nothing here:
  `(true; cd sub)` and `echo $(true; cd sub; pwd)` took the inner `cd`
  as this shell's (the row for the backtick form is changed to the
  read it now keeps);
- every brace of a part counts, in order: `{ { cd sub; }; }` moves the
  shell, `{ { cat a; }; }` reads `a`, and `{ cat a; } | { cat b; }`
  drops `a`, whose output feeds the pipe.

The splitter moves to repos/shell_split.py, as cli_traces.py was at
its line cap. The parser is shared, so Codex and Copilot commands
change in the same way.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a directory builtin in a job or a pipe keeps the directory

Settles the review point that `source env.sh & cat AGENTS.md` gave no
read: a backgrounded `source` cannot change the foreground shell's
directory, yet the walker forgot it, and the same held for a
backgrounded or piped `eval`, `.`, `pushd`, `popd` and computed `cd`
(`cd "$X" &`, `cd $(pwd) | cat`).

`_Walk.lose()` had two meanings: "a directory builtin went somewhere
unknown" and "the next chain starts where a gated cd may have left it".
It now means the first. A builtin backgrounded by `&` or run as a
pipeline stage ran in a subshell, so it leaves this shell's directory
and its movement flag alone, and the reads after it in the same command
are kept. The gated case sets the directory unknown itself, as before.
A builtin in this shell (`source env.sh; cat AGENTS.md`, `pushd sub >
/dev/null`) still loses the directory.

The rule is the shared parser's, so it holds for Codex and Copilot
commands too.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a failed read naming two files keeps the one it knows

Settles the review point that `_failed_read` decided "one file" from
the number of derived reads. The walker leaves out a relative operand
when its directory is not known, so in `/ws` a failed
`cd /ws/sub; cd -; cat missing.md /ws/AGENTS.md` gave one read,
`/ws/AGENTS.md`, and dropped it, though cat printed the guidance and
exited 1 for the missing file.

The walker now records how many files the last printing command named
(its operands, past the options and the prefix words the walker
skips), and `_failed_read` drops the reads only when that count is
one. A failed `cd -; cat /ws/AGENTS.md` still gives no read. The rule
is shared: the new rows cover a Claude Code Bash call, a Codex command
and a Copilot bash command.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a builtin in a job or a pipe leaves a later || its directory

Settles the review point that `source env.sh & false || cat AGENTS.md`
gave no read: the backgrounded `source` kept the foreground directory
but still set the walker's chain flag `moved`, so the `||` branch after
it dropped the directory. A piped `source env.sh | false || ...`, a
backgrounded `cd`, `pushd`, `eval` or `.`, a computed `cd` in a job or a
pipe, and a backgrounded or piped brace group or list did the same.

A directory builtin now sets `moved` only when it runs in this shell,
as `shell_moved` was already set. The flag is saved and restored with
the directory and `shell_moved` (one `_Spot`) at a backgrounded list
and at a piped or backgrounded brace group. A builtin in this shell
(`source env.sh; false || cat AGENTS.md`) still loses the directory for
the `||` branch. The parser is shared, so this holds for Codex and
Copilot commands too.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a quoted or escaped directory builtin name is the builtin

Settles the review point that `"source" "$ENV"` moved nothing: a part
with an expansion is not split by shlex, and the walker matched its
blank-split first word, `"source"` with its quotes, against the
builtins. A quoted or escaped `cd`, `pushd`, `popd`, `eval` or `.` with
a computed operand (`'cd' "$D"`, `\eval "$X"`, `c"d" "$D"`), and a
quoted `builtin`, `command`, `time` or `env` before one, were missed the
same way, so a later relative read in the same command or the next
Claude Code Bash call was taken at the old directory. The failed-read
rule's `cd` test had the same gap: a failed `"cd" sub && cat AGENTS.md`
kept its read.

A new `_unquoted` helper removes each blank-split word's quotes and
backslash escapes, as shlex does, without expanding anything (`"$D"`
stays `$D`). `_runs_dir` and `_is_cd` pass their words through it
before `_command_words` skips the prefixes; the words of a part shlex
does split are already unquoted, so they are not unquoted twice
(`'\cd'` names a program `\cd`, not the builtin). Keywords are still
matched before unquoting: a quoted `"if"` is no keyword.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a directory builtin the parser does not follow moves it

Settles the review points that `X="a b" cd "$D"` and `time -p cd sub`
moved nothing. The walker matched the builtins on blank-split words for
a part with an expansion, so an assignment holding a blank hid the
`cd`, and it skipped `time`, `command` or `builtin` only right before a
builtin's name, so an option between them (`time -p`, `command -p`,
`builtin --`) hid it too. A later relative read in the same command or
in the next Claude Code Bash call was then taken at the old directory.

Rather than one more special case per shape, one conservative fallback:
`_runs_dir` now reads a part's words with shlex where it can split them
(so an assignment with a blank is skipped like any other), and a new
`_may_run_dir` counts a part as moving the shell when a `builtin`,
`command` or `time` the walker did not skip is followed by a directory
builtin's name anywhere in the part. Text shlex cannot split is not
understood at all, so any builtin's name in it counts. The forms the
walker does follow are unchanged: `cd sub`, a backgrounded or piped
one, a subshell.

The failed-read rule is left as it was: a part before the read that is
not surely a `cd` keeps the read on a non-zero exit, as its exit may be
the one that failed. Its docstring says so. The contract's limits list
states the rule and points at the drop-only forms tracked in #374.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): only the command word can name a directory builtin

Settles the review point that the fallback for parts the parser does not
fully follow fired on a builtin's name anywhere in the part. `time find
. -name x`, `time git add .`, `command -v cd` or `builtin printf '%s' .`
marked the shell as moved, so every later relative Bash read of the
trace was dropped.

`_may_run_dir` and `_runs_dir` now look at the command word only: past
`builtin`, `command` and `time` with their options (`time -p`,
`command -p`, `--`), the next word moves the shell only if it is a
directory builtin. `command -v` / `-V` describes a command and runs
nothing. For text shlex cannot split, the words are unquoted one by one
and the same command word counts; when a quote up to it does not close
(`X="a b c" cd "$D`), any builtin's name in the part still counts.
`time -p cd sub`, `command -p cd sub` and `builtin -- cd sub` still
move. The contract's limits list and the changelog fragment state the
narrowed rule.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* refactor(repo): move a shell command's word helpers to shell_words

cli_traces.py is at its 800-line cap, and the next fixes to how the
walker finds a part's command word need room. The helpers that find the
command word past `NAME=value`, `builtin`, `command`, `time` and `env`,
and that tell whether it runs a directory builtin (`_command_words`,
`_command_at`, `_runs_dir`, `_may_run_dir`, `_is_cd`, `_run_name`, `_cd`,
`_unquoted` and their constants), move as they are to a new module
beside it, `repos/shell_words.py`. No code changes; architecture.md
names the module.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): time is the keyword only as the first unquoted word

Settles the review point that `X=1 time cd sub; cat a` and
`\time cd sub; cat a` read `sub/a` and moved the shell. Bash takes
`time` as its keyword only as the first word of a command, unquoted;
after an assignment, or quoted or escaped, it is /usr/bin/time, which
runs the `cd` in a child process, so the shell stays and `cat a` reads
`a`. The walker now skips `time` before a directory builtin, and as a
prefix with options, only when the part's raw text starts with the
keyword (`_time_keyword`); `_is_cd` follows it, so a failed
`X=1 time cd sub && cat AGENTS.md` keeps its read like any part that is
not surely a `cd`.

The same point found the reverse in `case x in a) cd sub;; esac`, which
moved nothing. A `case ... esac` is a compound the walker does not
follow: from its `case` part to its `esac`, a part naming a directory
builtin counts as moving the shell, and the reads in it are not kept,
as an arm may or may not run. Later arms and arms on their own lines
count too. The contract's limits list and the changelog fragment say
both.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a brace group holding one read is that read

Settles the review point that a failing `{ cat AGENTS.md; }`, alone or
after `cd sub &&`, kept its read at rc 0, so `guidance_read`, reach and
uptake counted a file the agent never saw. `_failed_read` took the
group's `{` and `}` as parts of their own: the `}` was the last part,
and the read before it was not a `cd`, so the failure could have been
another part's.

The braces are no longer parts there: a `}` part is skipped and the
`{` that opens a group is stripped, so a group holding one read is that
read, after any `cd` (`cd sub && { cat AGENTS.md; }`, nested groups
too). A group holding another command (`{ make; cat AGENTS.md; }`)
keeps its read, as before. The rule is shared, so Codex and Copilot
commands get it too; a test each. §4.1, §7 and the changelog fragment
say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a refused relative read after a move has no path

Settles the review question about `cd sub` followed by a refused
`cat AGENTS.md`: the denied read was kept with `AGENTS.md`, the path
from the start directory, although the shell was then in `sub` or
somewhere not known. The counts skip a denied read, but `events.jsonl`,
`tool_calls` and the `Read` steps of `compare` / `consistency` carried
a wrong path.

The read stays, as a call the agent made, but with no `path`:
`{"kind": "read", "denied": true}`. An absolute path in the same call
keeps its own. Every consumer of read events already reads `path` with
`.get` or skips a denied event first (`Transcript.reads()`,
`guidance_read`, `skill_usage`, uptake, `run_from_events`, which gives
a plain `Read` with no `file_path`); a test pins each. No schema
describes the events. §4.1 says a read may have no path.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* feat(repo): count the shell reads at a directory not known

Settles the review point that one `source .venv/bin/activate` drops
every later relative Bash read of the run with nothing in `result.json`
to say so: `guidance_read: []` then reads as "no guidance read", not
"not known".

`result.json` `process` gains `unknown_reads`, an int, `0` when there
are none: the relative reads a trace made at a directory the converter
could not follow, which give no read event. The walker counts the
relative files a printing command names once its directory is lost in
the command (`cd -; cat a`, `source env.sh && cat a`), and `shell_walk`
returns that count with the reads and the move. The Codex and Copilot
converters add it per command; the Claude Code converter adds it per
Bash call that was not refused, plus each relative read it drops after
an earlier call moved the shell (a failed one-file read is not counted:
it failed). `Transcript.unknown_reads` carries it to `process_metrics`.
No schema describes `process`; §4.1 documents the key next to
`guidance_read`, and the changelog fragment gains an "Added" entry.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* test(repo): pin a failed cd continued over a line as no read

Answers the review point that `_failed_read` splits the raw script and
so would keep a failed `cd \<newline>sub && cat AGENTS.md`. It does
not: `split_script` keeps a line continuation inside its part, so the
first part is still the `cd`, and the failed read gives no read. No
code change; the failed cd-then-cat test gains that form and
`cd sub \<newline>&& cat AGENTS.md`, which no test covered.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a hidden group's reads are not counted as unknown

Settles the review point that `process.unknown_reads` counted prints
whose output never reached the agent. In `{ source env.sh; cat
AGENTS.md; } > /dev/null`, or a group feeding a pipe, the walker drops
the group's read events, as its output is not shown, but kept the count
`printed()` had added for the group's relative files at a directory not
known: `shell_walk` gave no read and `unknown=1`, which the three
converters carry into `result.json`, so an empty `guidance_read` looked
uncertain.

An open brace group now saves the unknown count with its read mark, and
the close that drops the group's reads rolls the count back to it. A
nested hidden group rolls back only its own count, and a group whose
output is shown keeps its count. Tests through `shell_walk` and through
the Claude Code converter to `process_metrics`.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* docs(repo): reviewing.md says which shell reads guidance_read counts

The "Delivery first" step that came in with #365 said that
process:guidance_read counts Read-tool reads only. On this branch a
Claude Code Bash call, Codex command or Copilot bash command that only
prints files counts too, and process:unknown_reads counts the relative
reads dropped after the shell moved. Say that, and keep the pointer to
events.jsonl, agent.stdout or a process_metrics counter for the rest.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): repo report and compare show process:unknown_reads

Review point 4458839235 on #369: result.json's process block has carried
unknown_reads since 226a04c, but process_counts.PROCESS_KEYS did not
list it, so process_values({"process": {"guidance_read": [],
"unknown_reads": 3}}) gave only process:guidance_read, and a batch whose
every cell sourced a venv before cat AGENTS.md reported a guidance_read
mean of 0 and nothing else. reviewing.md already named
process:unknown_reads, which neither command printed.

PROCESS_KEYS now lists unknown_reads right after guidance_read, so
repo report's process line and repo compare's descriptive measures
carry it in the contract's §4.1 order. The tests pin process_values on
the reviewer's input, the report line and the compare row order.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): time with assignments, nested case, braces on a case part

Review point 4458839251 on #369: three forms of the round-9 case and
time handling kept a read at a wrong path or a hidden one.

- time X=1 cd sub; cat AGENTS.md gave (['AGENTS.md'], False, 0), but
  bash's time keyword times the whole simple command, so the cd runs in
  this shell. A time prefix may now be followed by NAME=value words
  before the directory builtin: shell_words._prefix_runs_dir where
  _command_words skips the prefix, and _command_at past time's options
  (so time -p X=1 cd sub counts as a move). It now gives
  (['sub/AGENTS.md'], True, 0); command X=1 cd and builtin X=1 cd,
  which run no cd, are unchanged.
- case $x in a) case $y in b) :;; esac; cd sub;; esac; cat AGENTS.md
  read sub/AGENTS.md: the inner esac ended the outer case. Inside a
  case each case word now opens one more level and only a leading esac
  closes one, so a miscount stays inside (reads dropped). It now gives
  ([], True, 1).
- { cat AGENTS.md; { case $x in a) :;; esac; }; } > /dev/null kept
  AGENTS.md: in_case returned before track_groups, so the brace opened
  on the case part was not tracked and the outer group's redirect
  closed nothing. A case part now tracks its braces first (before the
  lose() its builtin causes), giving ([], False, 0).

The contract's limits and the changelog fragment name the assignments
after time.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a failed one-file read adds nothing to unknown_reads

Settles review comment 4459651043 on #369. A shell command that names
one file at a directory the walker cannot follow (`cd -; cat missing.md`)
added 1 to `process.unknown_reads` when it started, and its failure never
took it back, although the same failure drops a known read's event.

`_failed_read` now decides from the printer's own operand count also when
no path was resolved, and each converter settles a command's unknown count
with its result: Codex keeps it with the started command's derived reads
and subtracts it on a failed one-file completion (a completion without a
start adds it only when it did not fail), Copilot keeps it per call id and
subtracts it on such a result, and the Claude Code Bash settlement adds it
only for calls that neither were refused nor failed as one read.

The contract's §4.1 `unknown_reads` row says that a failed one-file read
counts none.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a leading redirection is not a cd's command word

Settles review comment 4459651056 on #369. In `> /tmp/cd.log cd sub` the
`cd` runs in the shell, but the command-word lookup took `>` as the
command, so the move was missed and a later Bash `cat AGENTS.md` was
recorded as the root file's read.

`_command_words`, `_command_at` and `_prefix_runs_dir` now skip leading
redirections (`>`, `>>`, `<`, `&>`, `2>err`, `{fd}>x`; the target attached
or the next word), alongside the `NAME=value` words they already skip, and
also after `builtin`, `command` and `time`. Such a part is still not
followed (as `cd sub > log` is not), so the shell moves to a directory not
known: within the call the next relative read is dropped and counted in
`unknown_reads`, and so is the next call's. A redirected `cd` in a job or a
pipeline still moves nothing, and `> log time cd sub` stays
/usr/bin/time's child.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a redirection before a prefix's options hides no cd

Settles review comment 4459886479 on #369. `_command_at` skipped a
`builtin`, `command` or `time` prefix's options only before the
redirections that follow it, so in `command > /tmp/cd.log -p cd sub`
the command word came out as `-p`: the cd was missed, and a later
relative Bash read was recorded at the start directory.

`_past_prefix` now skips the prefix's options, redirections and, past
`time`, `NAME=value` words in one loop, in any order, until the command
word. Such a cd still loses the directory and moves the shell, as a
redirected cd does since the previous commit; `command > log -v cd`
still runs nothing.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* docs(repo): first_useful.steps counts a Claude Bash read as one more step

A derived read event is one more event, so a run that prints a file
through Bash before its first useful result shows one step more. The
changelog says so and a test pins it.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): the bash= probe may run only the cat it names

repo reach runs the shell on the host, so a probed CLAUDE.md could drive any command.
claude-code's bash mode adds a PreToolUse hook that blocks all but DOKIMI_REACH_COMMAND, and fails closed.

Signed-off-by: Alexander Rybkin <alexander.rybkin@intel.com>

* refactor(repo): keep repo.py and test_repo_useful.py under the growth caps

The reach flag check moves to reach.check_flags; the Bash first_useful test joins test_repo_events_bash.py.

Signed-off-by: Alexander Rybkin <alexander.rybkin@intel.com>

* fix(repo): a negated printer is no read

`! cat AGENTS.md` of a missing file exits 0, so it was read with rc 0; its exit no
longer says whether the file was printed, so it gives no read in any harness.

Signed-off-by: Alexander Rybkin <alexander.rybkin@intel.com>

* fix(repo): a negated read adds nothing to unknown_reads

! cat AGENTS.md at a directory not known gave no read but counted one
unknown read, as a pipe does not. Skip the printer before it is counted,
and name the negated read in the contract and reviewing.md as the
changelog does.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

---------

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>
Signed-off-by: Alexander Rybkin <alexander.rybkin@intel.com>
Co-authored-by: Alexander Rybkin <alexander.rybkin@intel.com>
napetrov pushed a commit to napetrov/dokimi that referenced this pull request Nov 4, 2026
* feat(repo): reach --scenarios shadow adds a CLAUDE.local.md

Follow-up to the dokimi review of IntelPython/dpnp#3099 (item 4). repo reach
probed the tree as it is, so on a tree with AGENTS.md files and no CLAUDE*
file it could not show that a CLAUDE* file turns them off, although
budget.py's `off` bullet said the reach probe re-measures that rule.

- Harness profiles take an optional guidance.shadow_file (harness_profile.v1
  widened in place); the claude-code profile sets it to CLAUDE.local.md.
- A new --scenarios kind, shadow, outside the default root,cwd,read:
  shadow=. writes the shadow file at the root and runs as cwd=.;
  shadow=<dir> writes it in each guidance directory holding a file not named
  CLAUDE* and runs as read=<dir>. A directory where the tree already has a
  file at that path is skipped. The file is seeded with its own tokens
  (distinct_salt counts them), never committed, and removed when its
  scenario ends, after an error too.
- Its result is a `shadow` record on the scenario row (guidance_reach.v1
  widened in place) and one line under the matrix; the matrix keeps one row
  per tree file. --dry-run lists the shadow scenarios with their file.
- A profile without guidance.shadow_file refuses the kind (exit 2). The
  --scenarios help names the default instead of "all".
- Contract sections 6 and 7 say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach shadow skips blocked paths, refuses probe-file parents

Settles two review points on the reach shadow scenarios.

A shadow path was free when no tree file sat at it or under it. It is
now also taken when a tree file sits above it (AGENTS.md for a shadow
file AGENTS.md/local.md) and when the tree holds a directory at it,
which the file list leaves out when the directory is empty: Shadow asks
the tree (RepoTree.is_dir) once per candidate path, and a path the tree
cannot resolve counts as taken.

In the workspace, a shadow path that would go under one of the probe's
own entries that is not a directory (a REACH_PROBE.txt, a seeded file,
a link) is refused with a ReachError before anything is written, as a
path that would replace one already was. The cleanup removes only what
the call made: the file once its write has begun, and the outermost
directory it created. An OSError while creating becomes a ReachError
naming the path, after that cleanup, so `repo reach` reports it as
`✗ ...` with exit 1 instead of a traceback.

The contract's §7 and the changelog fragment say what the skip covers.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach shadow treats a looping ignored link as taken

Settles review comment 4443412079 on intel#367. A git working tree can hold
an ignored CLAUDE.local.md that is a link to itself: it is in no file
list, so Shadow.free asks WorkTree.is_dir, and Path.resolve raises
RuntimeError on the loop before Python 3.13. That escaped as a
traceback from `repo reach --scenarios shadow`, --dry-run included.
Shadow.free now counts RuntimeError and OSError, the failures
WorkTree.resolve already maps, as taken, as it does a SourceError.
WorkTree.is_dir is unchanged for its other callers. On Python 3.13+
resolve does not raise for the loop, so the link reads as an ignored
non-directory, which the skeleton workspace never holds.

The tests use a real ignored looping link in a git working tree, for
the scenario list and for the --dry-run command, each also with
Path.resolve raising RuntimeError on the loop as before Python 3.13;
and a tree whose is_dir raises each of the three errors.

Comment 4443412060 needs no code change. The contract's skip line now
says what the code compares: the tree's files ignoring case, an empty
directory by the disk's own lookup.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach receipt leaves the shadow scenarios out

Review of intel#367 (comment 4445805701): `repo reach --format receipt`
built one receipt per scenario row and did not know about a row's
`shadow` record. A `shadow=.` receipt therefore described the tree as
committed while the run had a CLAUDE.local.md the tree lacks, and said
`AGENTS.md: expected true, observed not_loaded` with the shadow file
in none of its sources.

build_receipt now skips a row that carries a `shadow` record, for a
live run and for `--from` alike: the receipt describes the tree as
committed, and the shadow results stay in reach.json and the matrix.
Contract §7.1 and the changelog fragment say so; a test runs
`root,shadow` and gets a receipt with the `cwd=.` row only.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach checks shadow paths before any scenario runs

Review of intel#367 (comments 4445805709 and 4446227108): a shadow path that
went under or over a probe file (`shadow_file: REACH_PROBE.txt/x.md`)
was refused only when its own scenario started. With
`--scenarios root,cwd,read,shadow` the harness ran three times, and
was billed for them, before the ReachError, and no reach.json was
saved.

The workspace is the same in every scenario, so run_reach now checks
every planned shadow path once, right after build_workspace and before
the harness's version command or any scenario (_check_shadow_paths).
_shadowed keeps its own check. Contract §7 and the changelog fragment
say when the refusal comes; a test with a harness that counts its
calls gets the ReachError after none.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach --dry-run plans from the files a run probes

Review of intel#367 (comment 4446227118): `repo reach --dry-run` and the
`--only` check planned from probe_files(), before run_reach drops the
links it cannot follow. With `sub/AGENTS.md -> nowhere.md`, the dry run
listed `cwd=sub`, `read=sub` and `shadow=sub`, which a run never
executes: it lists the link under `unresolved` and probes nothing in
`sub/`.

followable() in repos/reach.py returns the probed files without those
links, with resolve_links's groups and unresolved list. run_reach and
the command both plan from it, so the dry run, the `--only` check and
the scenario count match the run for every kind. The dry run's `files`
key still lists every probed path. A test plants the dangling link: the
dry run lists `cwd=.` and `shadow=.` only, and `--only read=sub` is a
usage error. Changelog fragment, category Fixed.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach --dry-run refuses a tree of unfollowable links

Settles a review point on the reach shadow kind: with only
`AGENTS.md -> nowhere.md` as guidance, `repo reach --dry-run` (with
`--scenarios shadow --only shadow=.`, or the default `cwd=.`) listed a
scenario and exited 0, while a run stopped at run_reach's
"no guidance file to probe" guard with exit 1.

followable() now holds that guard, so run_reach and the command share
it. The command's planning moves into _reach_plan, which calls
followable() before the dry run, the --only check and the scenario
count, and exits 1 on that refusal as a run does.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach --dry-run refuses what a run refuses

Settles review comment 4447141458 on intel#367: with every shadow
path already in the tree (AGENTS.md, CLAUDE.local.md, sub/AGENTS.md,
sub/CLAUDE.local.md and --scenarios shadow), `repo reach --dry-run`
printed `"runs": []` and exited 0, while the run exited 2 with "no
scenario selected". _reach_plan returned from its --dry-run branch before
the count check.

The dry run now goes through the same path as a run up to its first
harness call. _reach_plan makes the count check in both modes, the
command makes its receipt-over-probe check before the dry run, and
run_reach takes dry_run: it builds the workspace (now in _prepare, shared
with the run), makes the checks of the build, removes the workspace and
returns the files and the planned runs before the harness's version
command. That also closes the other gaps a look over the run's refusals
found, each of which the dry run printed a plan for and exited 0: a
receipt that would replace the probe (2), a tree with no guidance file, a
guidance file above the workspace, a guidance file that is not UTF-8, a
tree path the workspace cannot hold, and a shadow path under a probe file
(1). Contract §7, the --dry-run help and the dry-run changelog fragment
say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach reports a --work-dir it cannot use, not a traceback

Settles review comment 4447340550 on the reach shadow follow-up: a
--work-dir that is missing, not a directory or not writable made
tempfile.mkdtemp raise FileNotFoundError, NotADirectoryError or
PermissionError, which neither run_reach nor the command caught, so a
dry run and a run alike ended in a traceback.

run_reach now makes its directory in _make_base, which turns that
OSError into a ReachError naming the directory; the command's existing
handler prints it as a single error line with exit 1. The same applies
to a write the workspace refuses while _prepare builds it (a full
disk): "cannot build the probe workspace <dir>: <reason>". _prepare
picks the salt before it builds, since that step reads only the tree,
so a tree read is not reported as a workspace failure. The out-dir
check already caught OSError, and removing the workspace ignores
failures, so neither needed a change.

Tests cover a missing, file-valued and unwritable (mkdtemp patched to
raise PermissionError) --work-dir and a full disk while seeding, each
in both modes; the contract's dry-run paragraph and the changelog
fragment say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach guards the shadow file's name above the workspace

Settles review comment 4447531771 on the reach shadow follow-up: the
check for guidance files above the workspace looked for the built-in
names and the profile's guidance.names only. A custom profile with
guidance.names [AGENTS.md] and guidance.shadow_file MEMORY.md, run with
a --work-dir that holds a MEMORY.md, passed that check, though a harness
that loads MEMORY.md by convention would read the one above the
workspace in every scenario.

_prepare now takes the names from _guarded: when a shadow scenario is
planned, the file name (last path part) of each planned shadow path,
which shadow_for has already checked, joins ANCESTOR_GUARD and the
profile's guidance names. The default CLAUDE.local.md was in
ANCESTOR_GUARD already. Without a shadow scenario the names are
unchanged. A run and a dry run share _prepare, so both refuse alike.

Tests: MEMORY.md, .memory/MEMORY.md and CLAUDE.local.md as shadow files,
each with its name in the --work-dir, give the same refusal and exit 1
in a dry run and a run, with no harness call; without a shadow scenario
the dry run plans as before. The contract's ancestor-guard line and the
changelog fragment say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach guards the shadow file's path above the workspace

Settles the review point that the ancestor guard kept only the last part
of guidance.shadow_file. For `shadow_file: .claude/CLAUDE.local.md` it
looked for `<ancestor>/CLAUDE.local.md` and missed
`<ancestor>/.claude/CLAUDE.local.md`, which the harness then loads in
every scenario; for `shadow_file: .claude/MEM.md` a plain `MEM.md`
above --work-dir, which that profile never loads, stopped the run.

_guarded now adds profile.shadow_file as given, a relative path that
shadow_for has already checked, when a shadow scenario is planned;
check_ancestors already takes such paths (`.claude/CLAUDE.md`). Without
a shadow scenario the guard is unchanged. Contract §7 says "the path as
given" instead of "last path part", and the changelog fragment says so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* test(repo): reach work-dir refusal takes the OS's own reason

Settles the review point that
test_repo_reach_with_a_work_dir_it_cannot_use_fails_cleanly_in_both_modes
failed on Windows for a missing --work-dir and for one that is a file:
it expected the POSIX texts "No such file or directory" and "Not a
directory", where Windows says "The system cannot find the path
specified". The code already printed a clean line there.

The test now builds the reason as the code does, from the OSError that
mkdtemp raises in that directory on this OS (strerror, else the
exception), and still asserts the whole line, the
"cannot make the probe workspace in --work-dir <dir>: " prefix
included, and exit 1, in a dry run and a run alike.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): reach names a tree with no guidance file before selection

Settles the review-body point that, on a tree with no guidance file, a
run and a dry run with `--scenarios cwd` exited 2 with
`no scenario selected`: the selection check in the command ran before
run_reach's own check for a file to probe, so the message named the
wrong cause.

The check moves to reach.check_files, which run_reach and the
command's _reach_plan both call; _reach_plan calls it right after
probe_files, before the scenarios are selected, beside the followable
guard and with its exit code. Such a tree now stops with
`no guidance files to probe` and exit 1 in both modes, as a run with
the default scenarios does on main. Changelog fragment: one entry.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

---------

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>
napetrov pushed a commit to napetrov/dokimi that referenced this pull request Nov 4, 2026
intel#369)

* fix(repo): Claude Code Bash reads count as reads; bash= reach scenario

Settles two points of an audit of a `dokimi repo run` replay on
IntelPython/dpnp#3099.

Item 6: under Claude Code, guidance_read counted the Read tool only. In
the replay 17 of 78 guidance cells printed an AGENTS.md with Bash
(`cd benchmarks; cat AGENTS.md`) and all had guidance_read []. The
claude-stream-json converter now runs cli_traces.shell_reads on each
Bash command, as the Codex and Copilot readers do since intel#116, and emits
a read event per printed file before the command event (same t, the
subagent's agent id). Claude Code keeps the shell's directory between
calls, so after an agent's call that ran a cd or pushd
(shell_reads_moved), its later relative reads are skipped and absolute
ones kept. On the tool_result, a hook or permission denial marks the
reads denied, an is_error result of a one-file, one-part read drops it
(cli_traces._failed_read), and otherwise the reads get rc 0. The new
logic sits in helpers, so events._apply drops from complexity 17 to 14.
process_metrics is unchanged; the contract (4.1, 6, 7, 7.1) and the
module docstrings say which shell reads count, now for all three
harnesses.

Item 7: no reach scenario measured whether a Bash read of a nested file
loads its directory's guidance. `repo reach --scenarios bash` adds
bash=<dir>, started at the root with the profile's new `bash` tool mode
(claude-code: --tools Bash), telling the agent to
`cat <dir>/REACH_PROBE.txt`. The default kinds stay root,cwd,read. A
profile without a bash mode (codex, copilot) is a usage error, exit 2.
harness_profile.v1 accepts the optional `tools.bash` key in place; it
is left out of delegation.none, whose propertyNames schema_compat holds
fixed. The receipt maps bash=<dir> as it maps read=<dir>.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a cd in a job or pipeline does not move the Bash shell

Review of intel#369 (comments 4443237154, 4443248498): shell_reads_moved()
returned the walker's chain flag `moved`, which says a cd was seen, not
that the shell the script runs in may have moved. `cd sub &`,
`{ cd sub; } | cat`, `{ cd sub; } &` and `cd sub && make &` all came back
as moved, so a later Bash call's `cat AGENTS.md` of the same agent lost
its root read.

_Walk now keeps `shell_moved` apart from `moved`: a cd, pushd or popd
sets it only outside a subshell, and it is saved with the directory at
the start of an && / || list and at a brace group's opening, and
restored wherever the directory is (a backgrounded list, a piped or
backgrounded group, and a list backgrounded at the end of the script).
`moved` and the reads of Codex and Copilot commands are unchanged.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): settle Claude Code Bash reads once the trace ends

Review of intel#369 (comments 4443237165, 4443237182). Two orders of the
stream-json trace gave wrong reads:

- A permission refusal can come back as an `is_error` tool_result
  (`Permission to use Bash has been denied`) and only later as a
  `permission_denials` entry in the final result. The error result
  dropped the read of a one-file `cat AGENTS.md`, so the denial marked a
  detached event: the trace lost the denied read and `tool_calls` was
  one short.
- A call's `cd` marked the agent's shell as moved at tool_use time, so a
  `cd sub` that a PreToolUse hook or the permissions refused still cost
  the next call's `cat AGENTS.md` its read.

The converter now records each Bash call (its agent, order, named
paths, whether it moves the shell, and ok / error / denied) and settles
them all after the last line: a denied call moves nothing and keeps its
reads, denied; a failed one-file read drops its read; after a call that
was not denied and may have moved the shell, only absolute reads are
kept; otherwise reads get rc 0. Read events are still inserted before
their command event at tool_use time, and only the dropped ones are
removed at the end, so every read keeps its place. events._apply stays
at complexity 14.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a refused or failed read is no read in reach or skill use

Review of intel#369 (comment 4443248578): Transcript.reads(), which reach's
classify and so the receipt's `read_by_tool` use, and arms.skill_usage
took every read event, including denied ones and failed ones (rc 1). A
refused `cat sub/AGENTS.md` made an already-loaded file `fetched` and its
receipt `states.accessed` true, and a refused read of an installed
SKILL.md counted the skill as used. The Read tool had the same bug
before the Bash reads of this PR.

Both now take only reads that showed the file (transcript.shown_read:
not denied, rc 0 or no result), as process_metrics' guidance_read
already did. The events stay in events.jsonl for audit.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): shell-quote the probe path in the bash= reach prompt

Review of intel#369 (comments 4443237195, 4443248319): the bash= prompt put
the probe path into the Bash command as it was. Repository directory
names keep spaces and shell metacharacters, so guidance in
`my package/AGENTS.md` asked for `cat my package/REACH_PROBE.txt`,
which reads `my` and `package/REACH_PROBE.txt`, and a `$` or `;` in the
name changed what the command does.

The operand is now reach.shell_word(path): shlex.quote of the path,
with `./` in front of a path that starts with `-`. Scenario.read keeps
the raw path, and the Read-tool prompt is unchanged. The fake harness
of test_repo_reach_bash.py parses the quoted operand with shlex.split
and runs the command as the prompt names it.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* test(repo): POSIX paths in the fake Bash commands of the bash= tests

Review of intel#369 (comment 4443248422): the fake harness of
test_repo_reach_bash.py built its Bash commands from str(Path). On
Windows that gives `cat sub\AGENTS.md`, which the POSIX shell parser
reads as `subAGENTS.md`, so the read-event and fetched assertions
would fail there.

The probe command is the prompt's own operand (since the quoting fix),
and the command that cats the directory's AGENTS.md is built with
as_posix() and shell-quoted. Test-only change.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a brace group's separators do not end the list around it

`cd sub && { echo a; echo b; } &` backgrounds the whole && list, so the
shell does not move, yet shell_reads_moved returned moved=True: the `;`
inside the group overwrote the saved start of the enclosing list
(`list_start` / `listed`), and the final `&` restored the state after
`cd sub` instead of the state before it. A following Claude Code Bash
`cat AGENTS.md` then lost its root read.

A brace group now saves the enclosing list's state when it opens and
restores it when it closes, so the group is one command of that list.
`cd sub && { cd x; cat a; } &` moves nothing either, while
`cd sub && { echo a; }` (not backgrounded) still moves. The same fix
makes `cd x && { cat f; cat h; } & cat g` read `g`, not `x/g`.

Settles review comment 4443584029 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a computed cd in a job or a pipeline moves no Bash shell

`cd "$X" &` and `cd sub | cat` run their `cd` in a subshell, yet
shell_reads_moved returned moved=True: a computed part (an expansion, a
pipe or a redirect) is not split into words, and `_Walk.words` called
`lose()` for its `cd` without knowing the part was backgrounded or piped.
A following Claude Code Bash `cat AGENTS.md` then lost its read.

`words` now takes the part's operator after it; for a backgrounded part
or a pipeline (an unquoted, unescaped `|`), `lose()` still drops the
directory for the rest of the script but does not mark the shell moved.
`cd "$X" &`, `cd "$X" | cat`, `cd sub | cat` and `echo | cd sub` move
nothing; `cd "$X"`, `cd "$X" && make`, `cd $(pwd)` and `cd a\|b` still
move.

Settles review comment 4443584037 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): one moved Bash shell for the parent and its subagents

The Claude Code converter kept the "shell may have moved" state per
agent: after the parent ran `cd sub`, a subagent's `cat AGENTS.md`
still gave a read of the root AGENTS.md (and the reverse). Claude Code
keeps the Bash directory as process state, and a Task subagent may well
share it, so such a read may name a file the agent was never shown.

`_settle_bash` now keeps one flag for the whole trace: once any
non-denied call may have moved the shell, every agent's later relative
reads are dropped, absolute ones kept. This only drops reads, so it is
safe whether subagents share the parent's shell or not. The per-agent
field of `_BashCall` goes. The test that pinned the per-agent model is
replaced by one test per direction (parent cd, then a subagent's read;
subagent cd, then the parent's). The contract's guidance_read row, the
`fetched` bullet and the "cannot show" list say so.

Settles review comment 4445790393 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a refused Skill call is no use of the skill

arms.skill_usage skipped a refused or failed SKILL.md read, but its
`Skill` branch had no such check: a Skill tool call that a hook or the
permissions refused (`denied`) still put the skill in `skills_used` and
made `skill_invoked` true, though the skill never ran.

The loop now skips a denied or failed event (`rc` not 0 or None) at the
top, before either branch. The same class of bug was in
uptake.arm_uptake: it skipped denied events, but a read of a file a
`patch:` arm added that failed (`rc` 1, no such file) still counted in
`uptake.reads`; it now takes only reads that showed the file
(transcript.shown_read). Tests: a hook-denied and a permission-denied
Skill call, and a failed read of an added file. The contract's
skills_used and uptake text say so.

Settles review comment 4445790411 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a failed cd-then-read command is no read

`_failed_read` dropped the read of a failed command only when the
command was one part. `cd sub && cat AGENTS.md` with no sub/AGENTS.md
exits 1, yet its read of sub/AGENTS.md stayed with `rc` 0, so
guidance_read, skills_used and reach's `fetched` counted a file the
agent never saw.

A one-file read after `cd` parts now counts as one read part: a
non-zero exit means the read did not run (`cd sub && cat f`, the cd
failed) or ran and failed (the exit after `;`, `&` or `||` is the
read's), and either way the file was not shown. A list whose other part
is not a `cd` (`make && cat f`, `cat f && cd sub`) keeps its read, as
the exit does not say which part failed. The rule is shared, so a Codex
or Copilot command gets the same fix. Tests: the reviewer's probe and
five more cd forms, three lists that keep their read, and a Copilot
row. The contract's guidance_read row and `fetched` bullet say so.

Settles review comment 4446227568 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a refused Bash read after a cd stays, denied

After a `cd sub` that ran, a hook-refused `cat AGENTS.md` lost its read
event: `_settle_bash` checked "the shell may have moved, so a relative
read is not known" before it checked the denial, and dropped the read.
Only the command event was left, so `tool_calls` was one short, and the
module docstring's promise that a refused call's reads stay, `denied`,
did not hold.

The denial is now checked first. A refused call ran nothing, so its
reads stay, `denied`, after a move too; a relative path is then taken
from the start directory, and guidance_read, reach and skill use skip
a denied read anyway. Test: a `cd sub`, then a `cat AGENTS.md` refused
by a hook or by `permission_denials`, keeps the denied read, counts 3
tool calls and gives no guidance_read.

Settles review comment 4446227577 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): eval, source and time cd move the Bash shell too

`shell_reads_moved` did not set `moved` for `eval "cd sub"`,
`source env.sh` or `time cd sub`, so after such a Claude Code Bash call a
later relative `cat AGENTS.md` was still recorded as a read of the root
AGENTS.md, though the shell may be elsewhere.

`eval`, `source` and `.` now lose the directory as `pushd` / `popd` do:
they may run a `cd` that is not seen, so the shell may have moved (and
within one call, a relative read after them is not recorded). `time`
before a directory builtin is skipped like `builtin` and `command`, so
`time cd sub` is a `cd` (`command cd sub` already was). The parser is
shared, so a Codex or Copilot command follows the same rule within the
command. A `cd` in a shell function defined and then called is still not
seen; the contract's "cannot show" list says so, and its guidance_read
row and `fetched` bullet name the new forms. Tests: each form's `moved`,
a later call's relative read, and reads within the call.

Settles review comment 4446227585 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* docs(repo): tool_calls counts kept shell reads, denied ones too

The contract's tool_calls row and the process_metrics docstring said
it counts the read event of each file a shell command printed. It
counts every event: a refused `cat AGENTS.md` keeps a denied read, and
a failed `cat AGENTS.md missing.md` keeps a read for both paths, since
the exit code does not say which file failed. Say so, so the count is
not taken for evidence that a file was shown.

Settles review comment 4446703136 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a failed Skill call is no use of the skill

skill_usage skips an event with a non-zero rc, but the Claude Code
converter set rc on read and command events only. A Skill call whose
tool_result is an error ("Skill lint could not be loaded") with no hook
refusal or permission denial stayed a plain tool event, so the skill
counted as used, invoked and correctly selected.

_apply_result now sets rc (0, or 1 on an error) on a Skill tool event as
it does on a read. No other consumer reads rc on a tool event (uptake's
mcp_calls, tool_calls, reach and the consistency check do not), so only
skill usage changes. A permission-denied Skill call now carries rc 1 next
to denied, as a permission-denied command does.

Settles review comment 4446703155 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a cd $(...) in a pipeline moves no Bash shell

A part holding a command substitution goes down the walker's subshell
branch, which marked the shell moved unless the part was backgrounded.
So `cd $(pwd) | cat` set shell_moved although the cd ran in a pipeline
stage, and the next Claude Code Bash call's `cat AGENTS.md` lost its
relative read.

Both branches that see a directory builtin with a computed operand now
ask one helper, _in_own_shell, whether the part runs in the script's
shell: not backgrounded, and holding no pipe outside quotes, escapes,
$( ... ) and backticks (so `cd $(echo a | tr a b)` still moves). The
computed-word branch of _Walk.words reuses _runs_dir_before_parens for
its builtin test, which is the same test on a part without parentheses.

Settles review comment 4446703160 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a failed time cd-then-read command is no read

_failed_read drops the read of a failed command that is one read of one
file after cd parts, but took a part for a cd only when its first word
was `cd`. The shell walker also runs a cd after `time`, `command`,
`builtin` or a NAME=value word, so a failing `time cd sub && cat
AGENTS.md` kept its sub/AGENTS.md read at rc 0, and guidance, skill use,
reach access and uptake counted a file that was never shown.

The test now goes through _command_words, the walker's own helper, so
the two agree: `time cd`, `command cd`, `builtin cd` and `X=1 cd` are a
cd, and `env cd` (no builtin runs) is not, as before. The helper is
shared by the Codex and Copilot readers too.

Settles review comment 4446703173 on intel#369.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): follow a brace group past the $( ) and groups in it

Settles the review point that `{ cd $(pwd); } | cat` and
`{ cd $(pwd); } &` moved the Bash shell: the part holding `$( )` was
skipped as a subshell before its `{` was seen, so the group's pipe or
`&` had nothing to restore, and a later relative `cat AGENTS.md` was
dropped.

The splitter now gives each part its outer text, the text outside any
`( ... )` or backticks. The walker tracks brace groups on that text
before it skips a subshell part, and tells a `cd $(...)` by it. So:

- a group whose first command holds `$( )` or backticks, or whose
  closing part does (`{ cd sub; } | grep $(x)`), opens and closes as
  any group;
- a `cd` inside `$( )`, backticks or `( ... )` moves nothing here:
  `(true; cd sub)` and `echo $(true; cd sub; pwd)` took the inner `cd`
  as this shell's (the row for the backtick form is changed to the
  read it now keeps);
- every brace of a part counts, in order: `{ { cd sub; }; }` moves the
  shell, `{ { cat a; }; }` reads `a`, and `{ cat a; } | { cat b; }`
  drops `a`, whose output feeds the pipe.

The splitter moves to repos/shell_split.py, as cli_traces.py was at
its line cap. The parser is shared, so Codex and Copilot commands
change in the same way.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a directory builtin in a job or a pipe keeps the directory

Settles the review point that `source env.sh & cat AGENTS.md` gave no
read: a backgrounded `source` cannot change the foreground shell's
directory, yet the walker forgot it, and the same held for a
backgrounded or piped `eval`, `.`, `pushd`, `popd` and computed `cd`
(`cd "$X" &`, `cd $(pwd) | cat`).

`_Walk.lose()` had two meanings: "a directory builtin went somewhere
unknown" and "the next chain starts where a gated cd may have left it".
It now means the first. A builtin backgrounded by `&` or run as a
pipeline stage ran in a subshell, so it leaves this shell's directory
and its movement flag alone, and the reads after it in the same command
are kept. The gated case sets the directory unknown itself, as before.
A builtin in this shell (`source env.sh; cat AGENTS.md`, `pushd sub >
/dev/null`) still loses the directory.

The rule is the shared parser's, so it holds for Codex and Copilot
commands too.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a failed read naming two files keeps the one it knows

Settles the review point that `_failed_read` decided "one file" from
the number of derived reads. The walker leaves out a relative operand
when its directory is not known, so in `/ws` a failed
`cd /ws/sub; cd -; cat missing.md /ws/AGENTS.md` gave one read,
`/ws/AGENTS.md`, and dropped it, though cat printed the guidance and
exited 1 for the missing file.

The walker now records how many files the last printing command named
(its operands, past the options and the prefix words the walker
skips), and `_failed_read` drops the reads only when that count is
one. A failed `cd -; cat /ws/AGENTS.md` still gives no read. The rule
is shared: the new rows cover a Claude Code Bash call, a Codex command
and a Copilot bash command.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a builtin in a job or a pipe leaves a later || its directory

Settles the review point that `source env.sh & false || cat AGENTS.md`
gave no read: the backgrounded `source` kept the foreground directory
but still set the walker's chain flag `moved`, so the `||` branch after
it dropped the directory. A piped `source env.sh | false || ...`, a
backgrounded `cd`, `pushd`, `eval` or `.`, a computed `cd` in a job or a
pipe, and a backgrounded or piped brace group or list did the same.

A directory builtin now sets `moved` only when it runs in this shell,
as `shell_moved` was already set. The flag is saved and restored with
the directory and `shell_moved` (one `_Spot`) at a backgrounded list
and at a piped or backgrounded brace group. A builtin in this shell
(`source env.sh; false || cat AGENTS.md`) still loses the directory for
the `||` branch. The parser is shared, so this holds for Codex and
Copilot commands too.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a quoted or escaped directory builtin name is the builtin

Settles the review point that `"source" "$ENV"` moved nothing: a part
with an expansion is not split by shlex, and the walker matched its
blank-split first word, `"source"` with its quotes, against the
builtins. A quoted or escaped `cd`, `pushd`, `popd`, `eval` or `.` with
a computed operand (`'cd' "$D"`, `\eval "$X"`, `c"d" "$D"`), and a
quoted `builtin`, `command`, `time` or `env` before one, were missed the
same way, so a later relative read in the same command or the next
Claude Code Bash call was taken at the old directory. The failed-read
rule's `cd` test had the same gap: a failed `"cd" sub && cat AGENTS.md`
kept its read.

A new `_unquoted` helper removes each blank-split word's quotes and
backslash escapes, as shlex does, without expanding anything (`"$D"`
stays `$D`). `_runs_dir` and `_is_cd` pass their words through it
before `_command_words` skips the prefixes; the words of a part shlex
does split are already unquoted, so they are not unquoted twice
(`'\cd'` names a program `\cd`, not the builtin). Keywords are still
matched before unquoting: a quoted `"if"` is no keyword.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a directory builtin the parser does not follow moves it

Settles the review points that `X="a b" cd "$D"` and `time -p cd sub`
moved nothing. The walker matched the builtins on blank-split words for
a part with an expansion, so an assignment holding a blank hid the
`cd`, and it skipped `time`, `command` or `builtin` only right before a
builtin's name, so an option between them (`time -p`, `command -p`,
`builtin --`) hid it too. A later relative read in the same command or
in the next Claude Code Bash call was then taken at the old directory.

Rather than one more special case per shape, one conservative fallback:
`_runs_dir` now reads a part's words with shlex where it can split them
(so an assignment with a blank is skipped like any other), and a new
`_may_run_dir` counts a part as moving the shell when a `builtin`,
`command` or `time` the walker did not skip is followed by a directory
builtin's name anywhere in the part. Text shlex cannot split is not
understood at all, so any builtin's name in it counts. The forms the
walker does follow are unchanged: `cd sub`, a backgrounded or piped
one, a subshell.

The failed-read rule is left as it was: a part before the read that is
not surely a `cd` keeps the read on a non-zero exit, as its exit may be
the one that failed. Its docstring says so. The contract's limits list
states the rule and points at the drop-only forms tracked in intel#374.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): only the command word can name a directory builtin

Settles the review point that the fallback for parts the parser does not
fully follow fired on a builtin's name anywhere in the part. `time find
. -name x`, `time git add .`, `command -v cd` or `builtin printf '%s' .`
marked the shell as moved, so every later relative Bash read of the
trace was dropped.

`_may_run_dir` and `_runs_dir` now look at the command word only: past
`builtin`, `command` and `time` with their options (`time -p`,
`command -p`, `--`), the next word moves the shell only if it is a
directory builtin. `command -v` / `-V` describes a command and runs
nothing. For text shlex cannot split, the words are unquoted one by one
and the same command word counts; when a quote up to it does not close
(`X="a b c" cd "$D`), any builtin's name in the part still counts.
`time -p cd sub`, `command -p cd sub` and `builtin -- cd sub` still
move. The contract's limits list and the changelog fragment state the
narrowed rule.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* refactor(repo): move a shell command's word helpers to shell_words

cli_traces.py is at its 800-line cap, and the next fixes to how the
walker finds a part's command word need room. The helpers that find the
command word past `NAME=value`, `builtin`, `command`, `time` and `env`,
and that tell whether it runs a directory builtin (`_command_words`,
`_command_at`, `_runs_dir`, `_may_run_dir`, `_is_cd`, `_run_name`, `_cd`,
`_unquoted` and their constants), move as they are to a new module
beside it, `repos/shell_words.py`. No code changes; architecture.md
names the module.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): time is the keyword only as the first unquoted word

Settles the review point that `X=1 time cd sub; cat a` and
`\time cd sub; cat a` read `sub/a` and moved the shell. Bash takes
`time` as its keyword only as the first word of a command, unquoted;
after an assignment, or quoted or escaped, it is /usr/bin/time, which
runs the `cd` in a child process, so the shell stays and `cat a` reads
`a`. The walker now skips `time` before a directory builtin, and as a
prefix with options, only when the part's raw text starts with the
keyword (`_time_keyword`); `_is_cd` follows it, so a failed
`X=1 time cd sub && cat AGENTS.md` keeps its read like any part that is
not surely a `cd`.

The same point found the reverse in `case x in a) cd sub;; esac`, which
moved nothing. A `case ... esac` is a compound the walker does not
follow: from its `case` part to its `esac`, a part naming a directory
builtin counts as moving the shell, and the reads in it are not kept,
as an arm may or may not run. Later arms and arms on their own lines
count too. The contract's limits list and the changelog fragment say
both.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a brace group holding one read is that read

Settles the review point that a failing `{ cat AGENTS.md; }`, alone or
after `cd sub &&`, kept its read at rc 0, so `guidance_read`, reach and
uptake counted a file the agent never saw. `_failed_read` took the
group's `{` and `}` as parts of their own: the `}` was the last part,
and the read before it was not a `cd`, so the failure could have been
another part's.

The braces are no longer parts there: a `}` part is skipped and the
`{` that opens a group is stripped, so a group holding one read is that
read, after any `cd` (`cd sub && { cat AGENTS.md; }`, nested groups
too). A group holding another command (`{ make; cat AGENTS.md; }`)
keeps its read, as before. The rule is shared, so Codex and Copilot
commands get it too; a test each. §4.1, §7 and the changelog fragment
say so.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a refused relative read after a move has no path

Settles the review question about `cd sub` followed by a refused
`cat AGENTS.md`: the denied read was kept with `AGENTS.md`, the path
from the start directory, although the shell was then in `sub` or
somewhere not known. The counts skip a denied read, but `events.jsonl`,
`tool_calls` and the `Read` steps of `compare` / `consistency` carried
a wrong path.

The read stays, as a call the agent made, but with no `path`:
`{"kind": "read", "denied": true}`. An absolute path in the same call
keeps its own. Every consumer of read events already reads `path` with
`.get` or skips a denied event first (`Transcript.reads()`,
`guidance_read`, `skill_usage`, uptake, `run_from_events`, which gives
a plain `Read` with no `file_path`); a test pins each. No schema
describes the events. §4.1 says a read may have no path.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* feat(repo): count the shell reads at a directory not known

Settles the review point that one `source .venv/bin/activate` drops
every later relative Bash read of the run with nothing in `result.json`
to say so: `guidance_read: []` then reads as "no guidance read", not
"not known".

`result.json` `process` gains `unknown_reads`, an int, `0` when there
are none: the relative reads a trace made at a directory the converter
could not follow, which give no read event. The walker counts the
relative files a printing command names once its directory is lost in
the command (`cd -; cat a`, `source env.sh && cat a`), and `shell_walk`
returns that count with the reads and the move. The Codex and Copilot
converters add it per command; the Claude Code converter adds it per
Bash call that was not refused, plus each relative read it drops after
an earlier call moved the shell (a failed one-file read is not counted:
it failed). `Transcript.unknown_reads` carries it to `process_metrics`.
No schema describes `process`; §4.1 documents the key next to
`guidance_read`, and the changelog fragment gains an "Added" entry.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* test(repo): pin a failed cd continued over a line as no read

Answers the review point that `_failed_read` splits the raw script and
so would keep a failed `cd \<newline>sub && cat AGENTS.md`. It does
not: `split_script` keeps a line continuation inside its part, so the
first part is still the `cd`, and the failed read gives no read. No
code change; the failed cd-then-cat test gains that form and
`cd sub \<newline>&& cat AGENTS.md`, which no test covered.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a hidden group's reads are not counted as unknown

Settles the review point that `process.unknown_reads` counted prints
whose output never reached the agent. In `{ source env.sh; cat
AGENTS.md; } > /dev/null`, or a group feeding a pipe, the walker drops
the group's read events, as its output is not shown, but kept the count
`printed()` had added for the group's relative files at a directory not
known: `shell_walk` gave no read and `unknown=1`, which the three
converters carry into `result.json`, so an empty `guidance_read` looked
uncertain.

An open brace group now saves the unknown count with its read mark, and
the close that drops the group's reads rolls the count back to it. A
nested hidden group rolls back only its own count, and a group whose
output is shown keeps its count. Tests through `shell_walk` and through
the Claude Code converter to `process_metrics`.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* docs(repo): reviewing.md says which shell reads guidance_read counts

The "Delivery first" step that came in with intel#365 said that
process:guidance_read counts Read-tool reads only. On this branch a
Claude Code Bash call, Codex command or Copilot bash command that only
prints files counts too, and process:unknown_reads counts the relative
reads dropped after the shell moved. Say that, and keep the pointer to
events.jsonl, agent.stdout or a process_metrics counter for the rest.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): repo report and compare show process:unknown_reads

Review point 4458839235 on intel#369: result.json's process block has carried
unknown_reads since 226a04c, but process_counts.PROCESS_KEYS did not
list it, so process_values({"process": {"guidance_read": [],
"unknown_reads": 3}}) gave only process:guidance_read, and a batch whose
every cell sourced a venv before cat AGENTS.md reported a guidance_read
mean of 0 and nothing else. reviewing.md already named
process:unknown_reads, which neither command printed.

PROCESS_KEYS now lists unknown_reads right after guidance_read, so
repo report's process line and repo compare's descriptive measures
carry it in the contract's §4.1 order. The tests pin process_values on
the reviewer's input, the report line and the compare row order.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): time with assignments, nested case, braces on a case part

Review point 4458839251 on intel#369: three forms of the round-9 case and
time handling kept a read at a wrong path or a hidden one.

- time X=1 cd sub; cat AGENTS.md gave (['AGENTS.md'], False, 0), but
  bash's time keyword times the whole simple command, so the cd runs in
  this shell. A time prefix may now be followed by NAME=value words
  before the directory builtin: shell_words._prefix_runs_dir where
  _command_words skips the prefix, and _command_at past time's options
  (so time -p X=1 cd sub counts as a move). It now gives
  (['sub/AGENTS.md'], True, 0); command X=1 cd and builtin X=1 cd,
  which run no cd, are unchanged.
- case $x in a) case $y in b) :;; esac; cd sub;; esac; cat AGENTS.md
  read sub/AGENTS.md: the inner esac ended the outer case. Inside a
  case each case word now opens one more level and only a leading esac
  closes one, so a miscount stays inside (reads dropped). It now gives
  ([], True, 1).
- { cat AGENTS.md; { case $x in a) :;; esac; }; } > /dev/null kept
  AGENTS.md: in_case returned before track_groups, so the brace opened
  on the case part was not tracked and the outer group's redirect
  closed nothing. A case part now tracks its braces first (before the
  lose() its builtin causes), giving ([], False, 0).

The contract's limits and the changelog fragment name the assignments
after time.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a failed one-file read adds nothing to unknown_reads

Settles review comment 4459651043 on intel#369. A shell command that names
one file at a directory the walker cannot follow (`cd -; cat missing.md`)
added 1 to `process.unknown_reads` when it started, and its failure never
took it back, although the same failure drops a known read's event.

`_failed_read` now decides from the printer's own operand count also when
no path was resolved, and each converter settles a command's unknown count
with its result: Codex keeps it with the started command's derived reads
and subtracts it on a failed one-file completion (a completion without a
start adds it only when it did not fail), Copilot keeps it per call id and
subtracts it on such a result, and the Claude Code Bash settlement adds it
only for calls that neither were refused nor failed as one read.

The contract's §4.1 `unknown_reads` row says that a failed one-file read
counts none.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a leading redirection is not a cd's command word

Settles review comment 4459651056 on intel#369. In `> /tmp/cd.log cd sub` the
`cd` runs in the shell, but the command-word lookup took `>` as the
command, so the move was missed and a later Bash `cat AGENTS.md` was
recorded as the root file's read.

`_command_words`, `_command_at` and `_prefix_runs_dir` now skip leading
redirections (`>`, `>>`, `<`, `&>`, `2>err`, `{fd}>x`; the target attached
or the next word), alongside the `NAME=value` words they already skip, and
also after `builtin`, `command` and `time`. Such a part is still not
followed (as `cd sub > log` is not), so the shell moves to a directory not
known: within the call the next relative read is dropped and counted in
`unknown_reads`, and so is the next call's. A redirected `cd` in a job or a
pipeline still moves nothing, and `> log time cd sub` stays
/usr/bin/time's child.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): a redirection before a prefix's options hides no cd

Settles review comment 4459886479 on intel#369. `_command_at` skipped a
`builtin`, `command` or `time` prefix's options only before the
redirections that follow it, so in `command > /tmp/cd.log -p cd sub`
the command word came out as `-p`: the cd was missed, and a later
relative Bash read was recorded at the start directory.

`_past_prefix` now skips the prefix's options, redirections and, past
`time`, `NAME=value` words in one loop, in any order, until the command
word. Such a cd still loses the directory and moves the shell, as a
redirected cd does since the previous commit; `command > log -v cd`
still runs nothing.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* docs(repo): first_useful.steps counts a Claude Bash read as one more step

A derived read event is one more event, so a run that prints a file
through Bash before its first useful result shows one step more. The
changelog says so and a test pins it.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

* fix(repo): the bash= probe may run only the cat it names

repo reach runs the shell on the host, so a probed CLAUDE.md could drive any command.
claude-code's bash mode adds a PreToolUse hook that blocks all but DOKIMI_REACH_COMMAND, and fails closed.

Signed-off-by: Alexander Rybkin <alexander.rybkin@intel.com>

* refactor(repo): keep repo.py and test_repo_useful.py under the growth caps

The reach flag check moves to reach.check_flags; the Bash first_useful test joins test_repo_events_bash.py.

Signed-off-by: Alexander Rybkin <alexander.rybkin@intel.com>

* fix(repo): a negated printer is no read

`! cat AGENTS.md` of a missing file exits 0, so it was read with rc 0; its exit no
longer says whether the file was printed, so it gives no read in any harness.

Signed-off-by: Alexander Rybkin <alexander.rybkin@intel.com>

* fix(repo): a negated read adds nothing to unknown_reads

! cat AGENTS.md at a directory not known gave no read but counted one
unknown read, as a pipe does not. Skip the printer before it is counted,
and name the negated read in the contract and reviewing.md as the
changelog does.

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>

---------

Signed-off-by: Anton Volkov <antonwolfy@gmail.com>
Signed-off-by: Alexander Rybkin <alexander.rybkin@intel.com>
Co-authored-by: Alexander Rybkin <alexander.rybkin@intel.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants