Repository navigation
Add AGENTS.md guidance for coding agents - #3099
Merged
Merged
Conversation
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.
antonwolfy
requested review from
ndgrigorian and
vlad-perevezentsev
as code owners
October 14, 2026 18:49
Contributor
|
View rendered docs @ https://intelpython.github.io/dpnp/index.html |
Contributor
|
Array API standard conformance tests for dpnp=0.22.0dev0=np2py314h8d9cdd5_13 ran successfully. |
-m "slow or not slow" now runs slow tests, "0" disables the test env flags, and large-allocation tests skip on USMAllocationError.
Collaborator
4 of 7 tasks
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.
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.
2 tasks done
ndgrigorian
approved these changes
Oct 28, 2026
ndgrigorian
left a comment
Collaborator
There was a problem hiding this comment.
Don't see a problem, LGTM
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.
This was referenced Oct 29, 2026
This was referenced Oct 29, 2026
Merged
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
This was referenced Oct 30, 2026
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>
This was referenced Nov 2, 2026
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR adds
AGENTS.mdfiles 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.mdand.github/instructions/*files proposed there are not added, because Copilot readsAGENTS.mdand they would only duplicate it.How the content was built:
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.mdunlesscontext.fileNamein its settings includesAGENTS.md.AGENTS.mdonly when there is no projectCLAUDE.md,.claude/CLAUDE.mdorCLAUDE.local.mdin the working directory or above it, and skips a nestedAGENTS.mdwhose own directory has one. So the repository should not gain aCLAUDE.md. A personal~/.claude/CLAUDE.mdor a managedCLAUDE.mddoesn't count and loads alongsideAGENTS.md. Contributors who keep aCLAUDE.local.mdneed to set "Project instructions" toclaude-md-and-agents-md. Before v2.1.281, some sessions, such as those on Amazon Bedrock or with telemetry disabled, read onlyCLAUDE.md.AGENTS.mdprecedence, so review-critical rules are kept in the root file.Checklist: