feat(repo): effective-instructions receipt for repo reach

dokimi/changelog.d/20261031_132853_napetrov_effective-instructions-receipt.md

@@ -0,0 +1,8 @@
+<!--
+Copyright (C) 2026 Intel Corporation
+SPDX-License-Identifier: Apache-2.0
+-->
+
+### Added
+
+- **An effective-instructions receipt for a reach probe** — `repo reach --format receipt` prints, and writes to `effective_instructions.json` in `--out`, the receipt of `effective-instructions/v0` (agentsmd/agents.md#213) for each probed scenario: each guidance source's path, sha256, scope, expected state (from `repo budget`'s start-up rules, Claude Code only), observed state (`loaded`, `fetched`, `not_loaded` or `unknown`), `observation_method` (`unknown`) with dokimi's own `dokimi_method` (`marker_self_report`: the model reports the marker tokens it sees; the prompt is not captured), the harness's name and version, the displacements seen in the run, and the unknowns. `repo reach --from <reach.json> --format receipt` builds the same receipt from a saved probe without a harness run, after checking the file's repository, harness and commit against the source; with `--from`, both must be at a commit (a working tree is a usage error, exit 2), and the receipt may not be written over the saved file. `followed` is always `unknown`: the probe does not show what the model did with a loaded source. The receipt makes no LLM call and is validated against `schemas/effective_instructions.v1.json`. The mapping and its limits are in `docs/repo-evaluation-contract.md` §7.1. The default output of `repo reach` is unchanged. With `--from`, every probe flag is refused when given, including at its default value, and an empty `--from` name is a usage error (exit 2); the receipt's unknowns name a truncated record and an error record separately.

dokimi/docs/reference/cli-interface.json

@@ -10859,7 +10859,7 @@
               "action": "_StoreAction",
               "choices": null,
               "const": null,
-              "default": 0.1,
+              "default": null,
               "group_key": null,
               "group_required": null,
               "hidden": false,
@@ -10903,6 +10903,41 @@
               "required": false,
               "type": null
             },
+            {
+              "action": "_StoreAction",
+              "choices": [
+                "'matrix'",
+                "'receipt'"
+              ],
+              "const": null,
+              "default": "matrix",
+              "group_key": null,
+              "group_required": null,
+              "hidden": false,
+              "is_flag": false,
+              "key": "--format",
+              "kind": "option",
+              "nargs": null,
+              "position": null,
+              "required": false,
+              "type": null
+            },
+            {
+              "action": "_StoreAction",
+              "choices": null,
+              "const": null,
+              "default": null,
+              "group_key": null,
+              "group_required": null,
+              "hidden": false,
+              "is_flag": false,
+              "key": "--from",
+              "kind": "option",
+              "nargs": null,
+              "position": null,
+              "required": false,
+              "type": null
+            },
             {
               "action": "_StoreAction",
               "choices": null,
@@ -10987,7 +11022,7 @@
               "action": "_StoreAction",
               "choices": null,
               "const": null,
-              "default": 4,
+              "default": null,
               "group_key": null,
               "group_required": null,
               "hidden": false,
@@ -11012,7 +11047,7 @@
               "kind": "option",
               "nargs": null,
               "position": null,
-              "required": true,
+              "required": false,
               "type": null
             },
             {
@@ -11035,7 +11070,7 @@
               "action": "_StoreAction",
               "choices": null,
               "const": null,
-              "default": "reach-out",
+              "default": null,
               "group_key": null,
               "group_required": null,
               "hidden": false,
@@ -11067,7 +11102,7 @@
               "action": "_StoreAction",
               "choices": null,
               "const": null,
-              "default": "root,cwd,read",
+              "default": null,
               "group_key": null,
               "group_required": null,
               "hidden": false,
@@ -11083,7 +11118,7 @@
               "action": "_StoreAction",
               "choices": null,
               "const": null,
-              "default": 300,
+              "default": null,
               "group_key": null,
               "group_required": null,
               "hidden": false,
@@ -13036,6 +13071,7 @@
                 "'answers'",
                 "'arms'",
                 "'cli_routes'",
+                "'effective_instructions'",
                 "'eval'",
                 "'eval_coverage'",
                 "'explore_runs'",

dokimi/docs/repo-evaluation-contract.md

@@ -1077,6 +1077,104 @@ per scenario).
   token was in the request bytes. This settles cells where the model
   under-reports, which is how a small model produces false `truncated` cells.
 
+### 7.1 Effective-instructions receipt (`effective_instructions.v1`)
+
+`repo reach --format receipt` prints, and writes to `effective_instructions.json`
+in `--out`, a receipt in the shape of `effective-instructions/v0`
+(agentsmd/agents.md#213). It is built from the reach payload and from the
+start-up chain of `repo budget` (`repos/budget.py`). It makes no
+LLM call. `repo reach --from <reach.json> --format receipt` builds the same
+receipt from a saved probe without running the harness. The source is read
+again: the file must be for the same repository, harness and commit (a
+different one is a usage error, exit 2). With `--from`, a receipt also needs a
+pinned source (`<path>@<rev>`) and a saved probe made at a commit: a working
+tree, or a probe of one (`repo.sha` null), is a usage error (exit 2), because
+`sha256` and the expectations are computed from the source as it is at
+conversion time and a working tree can change after the probe. A live
+`repo reach --format receipt` run is not held to this: it builds the receipt
+from the source it probes, but it reads `sha256` and the expectations after
+the harness exits. An edit to a guidance file made while the run is in flight
+therefore appears in the receipt next to the observations of the old text;
+the receipt's `unknowns` says so for a working tree, and a pinned source
+(`<path>@<rev>`) has no such window. The matrix (without `--format receipt`)
+still accepts an unpinned source. The harness configuration is not
+pinned: `expected` comes from the harness profile as it is at conversion time,
+and its guidance names and import depth are not compared with the probe's, so
+a receipt is the same only for an unchanged profile. The receipt is written
+beside the saved file; a name that resolves to the saved probe is a usage error
+(exit 2), and a write that fails is a runtime failure (exit 1). The probe-only flags (`--model`,
+`--budget`, `--scenarios`, `--only` and the rest) cannot be combined with
+`--from`. The schema is `schemas/effective_instructions.v1.json`; the code is
+`repos/receipt.py`.
+
+One artifact is written to `effective_instructions.json`, with one entry in its
+`receipts` array per reach scenario and `run_id` `<salt>:<scenario id>`.
+Each source carries:
+
+| Receipt field | From | Meaning |
+|---|---|---|
+| `path`, `alias_of` | reach `files`, `aliases` | a link is `adapter` scope and takes its target's tokens |
+| `sha256` | the text dokimi reads (LF-normalised UTF-8) | null when the file is not readable as text |
+| `scope` | path | `repo` for a root-level file and for `.claude/CLAUDE.md` and `.claude/AGENTS.md` only; `subtree` for a nested AGENTS.md, CLAUDE.md or CLAUDE.local.md (`.claude/CLAUDE.local.md` included); else `unknown` (a skill, for one) |
+| `expected` | budget `when` | see the table below |
+| `observed` | reach class | `loaded` → loaded, `fetched` → fetched, `not_loaded` → not_loaded, `truncated` and `error` → unknown |
+| `observation_method` | | `unknown` for every source: the thread vocabulary's method, since no runtime event, prompt capture or hook backs the probe |
+| `dokimi_method` | | `marker_self_report` for a source the probe recorded; null for a start-up file budget found and reach did not probe |
+| `states.accessed` | the harness's read events | `true` if the harness reported a read of the file (the Read tool; Codex and Copilot also report supported shell reads, §7); for a probed source `false` with tools off, else `unknown`; always `unknown` for a start-up file budget found and reach did not probe |
+| `states.selected` | the class | `true` for loaded or fetched (the source entered the request, by the harness or a read), else `unknown` |
+| `states.loaded` | the class | `true` for loaded, `false` for not_loaded, `unknown` for fetched, truncated and error: a tool read is not proof that start-up loading did not happen |
+| `states.followed` | | always `unknown` (the schema's `const`) |
+
+`runtime` is the harness's name and version, as reach records them. `model` is
+the string passed with `--model`, not the harness's name or a resolved model
+version. `observation.method` is `unknown` and `observation.dokimi_method` is
+`marker_self_report`: the model reports the tokens it can see, and the request
+sent to the provider is not captured. A reported token is evidence of loading,
+not a copy of the bytes received. The name is not `prompt_capture`, because
+dokimi does not capture the prompt.
+
+**Expected state.** budget's start-up rules are Claude Code's, so they apply
+only to `claude-code` runs; for other harnesses every `expected` is `unknown`
+and the receipt says so.
+
+| budget `when` | `expected` | Reason |
+|---|---|---|
+| `start` | `true` | loaded at start-up in every run |
+| `off` | `false` | a root CLAUDE\*.md turns AGENTS.md off |
+| `lazy`, run directory is the file's directory or inside it | `true` | loaded when the work reaches that directory |
+| `lazy`, run directory outside it | `false` | not reached by this run |
+| `lazy` on a link, an import, a root file, or a file another guidance file `@`-imports | `unknown` | budget's flattened `when` does not say which directory activates the file, so only a nested AGENTS/CLAUDE file that budget lists under its own path, and that no guidance file imports, gets a verdict |
+| `on demand` or absent | `unknown` | budget does not say |
+
+**Precedence.** `precedence_observed` lists a displacement only: a root
+CLAUDE\*.md (`CLAUDE.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md`) observed
+loaded in a run, with an `off` AGENTS.md observed not_loaded in that run. It
+does not give an order of entry. The displacement follows budget's rule as
+written (`repos/budget.py`): an AGENTS.md is `off` while a root CLAUDE\*.md
+exists, nested ones included, unless a root CLAUDE\* file aliases it or
+`@`-imports it (`start`), or a nested CLAUDE\* file `@`-imports it (`lazy`). So
+nested AGENTS.md files can appear, and an AGENTS.md at the root is not always
+`off`. If budget's rule changes, the receipt follows it.
+
+**What the marker method can and cannot show.** It shows which tokens were
+reported in a run, so it can support `loaded`, `fetched` and `not_loaded` as
+observations of that run. It cannot show:
+
+- that an instruction was followed (`followed` is always `unknown`);
+- a read through a shell that the harness does not normalise into a read
+  event (`cat`, `rg`, `grep` under Claude Code; Codex and Copilot normalise
+  only the shell commands §7 lists);
+- when a source entered the request, or in what order (no timestamps);
+- start-up imports and skill listings from budget, which reach does not probe:
+  they appear with `observed: unknown`. A skill body is loaded on demand, so it
+  is not listed; the receipt-level unknown says both;
+- anything a model under-reports; a prose-heavy answer is flagged.
+
+Each run lists its own `unknowns` (no usable answer, a source with one token
+reported, prose above the limit, unseeded tokens). The receipt-level `unknowns`
+repeat the limits above and carry the notice that start-up imports and skill
+listings are not probed.
+
 ## 8. L0 scan (`repo_readiness.v1`)
 
 `repo scan <source>` checks every mechanically checkable claim in the guidance

dokimi/dokimi/artifacts.py

@@ -12,7 +12,8 @@
 what moves it), ``repo_environment`` (static inspection of what a
 repository offers an agent), ``plan`` (the cells a run promises to measure),
 ``result`` (one status per planned cell), ``repo_budget`` (what a repository puts
-into an agent's context), ``need_graph`` and ``eval_coverage`` (a frozen need graph and an
+into an agent's context), ``effective_instructions`` (the effective-instructions/v0
+receipt of a reach probe), ``need_graph`` and ``eval_coverage`` (a frozen need graph and an
 eval set's coverage of it) and ``task_inspect`` (which eval-task format each
 path under a tree is). This module stamps each with a
 ``schema_version`` and validates it against the JSON Schema in
@@ -57,6 +58,7 @@
     "plan": "plan.v1",
     "result": "result.v1",
     "repo_budget": "repo_budget.v1",
+    "effective_instructions": "effective_instructions.v1",
     "task_inspect": "task_inspect.v1",
     "cli_routes": "cli_routes.v1",
     "need_graph": "need_graph.v1",