feat(repo): reach conformance suite and a nightly agent x version matrix

.github/.licenserc.yaml

@@ -51,6 +51,10 @@ header:
     - 'AGENTS.md'
     - 'dokimi/data/agent_profiles/**'
     - 'dokimi/data/skills/**'
+    # Reach conformance fixtures: the CLAUDE.md and AGENTS.override.md files a harness loads verbatim (AGENTS.md is
+    # ignored above, at any depth).
+    - 'dokimi/data/reach-conformance/**/CLAUDE.md'
+    - 'dokimi/data/reach-conformance/**/AGENTS.override.md'
     # Eval oracles: patches applied to the workspace and reference answers
     # written verbatim as the agent's answer (.agent-eval/run.py).
     - '.agent-eval/tasks/**/*.patch'

.github/workflows/reach-matrix.yml

@@ -0,0 +1,215 @@
+# Copyright (C) 2026 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+name: reach-matrix
+
+# Paid model calls, so never a PR check; a harness without a model, credential or CLI is skipped, not failed.
+# Design and secrets: dokimi/docs/reach-matrix.md.
+on:
+  schedule:
+    - cron: '37 4 * * *'
+  workflow_dispatch:
+
+permissions: {}
+
+defaults:
+  run:
+    shell: bash
+
+concurrency:
+  group: ${{ github.workflow }}
+  cancel-in-progress: false
+
+jobs:
+  claude-code:
+    permissions:
+      contents: read
+    runs-on: ${{ github.repository_owner == 'intel' && 'intel-ubuntu-latest' || 'ubuntu-latest' }}
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: '3.13'
+          cache: pip
+          cache-dependency-path: dokimi/requirements.lock.txt
+      - name: Install dokimi
+        working-directory: dokimi
+        run: pip install --require-hashes -r requirements.lock.txt
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
+        with:
+          node-version: '22'
+      - name: Check the credential
+        id: creds
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
+        run: |
+          if [ -n "$ANTHROPIC_API_KEY" ]; then backend=anthropic
+          elif [ -n "$AWS_BEARER_TOKEN_BEDROCK" ]; then backend=bedrock
+          else backend=none; fi
+          echo "backend=$backend" >> "$GITHUB_OUTPUT"
+          if [ "$backend" = none ]; then echo "present=false" >> "$GITHUB_OUTPUT"; else echo "present=true" >> "$GITHUB_OUTPUT"; fi
+      - name: Install the CLI
+        if: steps.creds.outputs.present == 'true' && vars.REACH_MODEL_CLAUDE_CODE != ''
+        run: npm install -g @anthropic-ai/claude-code@2.1.316
+      - name: Run reach over the fixtures
+        working-directory: dokimi
+        env:
+          PYTHONPATH: .
+          REACH_MODEL: ${{ vars.REACH_MODEL_CLAUDE_CODE }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          AWS_BEARER_TOKEN_BEDROCK: ${{ secrets.AWS_BEARER_TOKEN_BEDROCK }}
+          CLAUDE_CODE_USE_BEDROCK: ${{ steps.creds.outputs.backend == 'bedrock' && '1' || '' }}
+          AWS_REGION: ${{ vars.AWS_REGION }}
+        run: python scripts/reach_conformance.py run --harness "claude-code=$REACH_MODEL" --out reach-out
+      - name: Upload the matrix
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: reach-matrix-claude-code
+          path: dokimi/reach-out/claude-code.matrix.json
+          if-no-files-found: warn
+          retention-days: 30
+
+  codex:
+    permissions:
+      contents: read
+    runs-on: ${{ github.repository_owner == 'intel' && 'intel-ubuntu-latest' || 'ubuntu-latest' }}
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: '3.13'
+          cache: pip
+          cache-dependency-path: dokimi/requirements.lock.txt
+      - name: Install dokimi
+        working-directory: dokimi
+        run: pip install --require-hashes -r requirements.lock.txt
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
+        with:
+          node-version: '22'
+      - name: Check the credential
+        id: creds
+        env:
+          CODEX_API_KEY: ${{ secrets.CODEX_API_KEY }}
+        run: |
+          if [ -n "$CODEX_API_KEY" ]; then echo "present=true" >> "$GITHUB_OUTPUT"; else echo "present=false" >> "$GITHUB_OUTPUT"; fi
+      - name: Install the CLI
+        if: steps.creds.outputs.present == 'true' && vars.REACH_MODEL_CODEX != ''
+        run: npm install -g @openai/codex@0.166.0
+      - name: Run reach over the fixtures
+        working-directory: dokimi
+        env:
+          PYTHONPATH: .
+          REACH_MODEL: ${{ vars.REACH_MODEL_CODEX }}
+          CODEX_API_KEY: ${{ secrets.CODEX_API_KEY }}
+        run: python scripts/reach_conformance.py run --harness "codex=$REACH_MODEL" --out reach-out
+      - name: Upload the matrix
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: reach-matrix-codex
+          path: dokimi/reach-out/codex.matrix.json
+          if-no-files-found: warn
+          retention-days: 30
+
+  copilot:
+    permissions:
+      contents: read
+    runs-on: ${{ github.repository_owner == 'intel' && 'intel-ubuntu-latest' || 'ubuntu-latest' }}
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: '3.13'
+          cache: pip
+          cache-dependency-path: dokimi/requirements.lock.txt
+      - name: Install dokimi
+        working-directory: dokimi
+        run: pip install --require-hashes -r requirements.lock.txt
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1  # v7.1.0
+        with:
+          node-version: '22'
+      - name: Check the credential
+        id: creds
+        env:
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+        run: |
+          if [ -n "$COPILOT_GITHUB_TOKEN" ]; then echo "present=true" >> "$GITHUB_OUTPUT"; else echo "present=false" >> "$GITHUB_OUTPUT"; fi
+      - name: Install the CLI
+        if: steps.creds.outputs.present == 'true' && vars.REACH_MODEL_COPILOT != ''
+        run: npm install -g @github/copilot@1.0.105
+      - name: Run reach over the fixtures
+        working-directory: dokimi
+        env:
+          PYTHONPATH: .
+          REACH_MODEL: ${{ vars.REACH_MODEL_COPILOT }}
+          COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+        run: python scripts/reach_conformance.py run --harness "copilot=$REACH_MODEL" --out reach-out
+      - name: Upload the matrix
+        if: always()
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: reach-matrix-copilot
+          path: dokimi/reach-out/copilot.matrix.json
+          if-no-files-found: warn
+          retention-days: 30
+
+  matrix:
+    needs: [claude-code, codex, copilot]
+    if: always()
+    permissions:
+      contents: read
+    runs-on: ${{ github.repository_owner == 'intel' && 'intel-ubuntu-latest' || 'ubuntu-latest' }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        with:
+          python-version: '3.13'
+          cache: pip
+          cache-dependency-path: dokimi/requirements.lock.txt
+      - name: Install dokimi
+        working-directory: dokimi
+        run: pip install --require-hashes -r requirements.lock.txt
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2
+        with:
+          pattern: reach-matrix-*
+          merge-multiple: true
+          path: dokimi/reach-in
+      - name: Merge the matrices
+        working-directory: dokimi
+        env:
+          PYTHONPATH: .
+        run: |
+          missing=0
+          for harness in claude-code codex copilot; do
+            if [ ! -f "reach-in/$harness.matrix.json" ]; then
+              echo "::error::no $harness matrix: its job failed before writing one"
+              missing=1
+            fi
+          done
+          [ "$missing" -eq 0 ] || exit 1
+          python scripts/reach_conformance.py merge reach-in/*.matrix.json \
+            --out reach-out/reach-matrix.json --md reach-out/reach-matrix.md
+          cat reach-out/reach-matrix.md >> "$GITHUB_STEP_SUMMARY"
+      - name: Upload the matrix page
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9  # v7.0.2
+        with:
+          name: reach-matrix
+          path: |
+            dokimi/reach-out/reach-matrix.json
+            dokimi/reach-out/reach-matrix.md
+          if-no-files-found: error
+          retention-days: 90

dokimi/benchmarks/spec.v1.yaml

@@ -76,7 +76,7 @@ future:
 # that matched almost nothing, max_docs one that escaped; raise it with each new doc.
 golden_manifest:
   min_docs: 10
-  max_docs: 37
+  max_docs: 38
   include:
     - docs/**/*.md
   exclude:

dokimi/changelog.d/20261031_160000_napetrov_reach-matrix.md

@@ -0,0 +1,8 @@
+<!--
+Copyright (C) 2026 Intel Corporation
+SPDX-License-Identifier: Apache-2.0
+-->
+
+### Added
+
+- **A reach conformance suite and a nightly agent × version matrix** — `data/reach-conformance/` holds eight fixture repositories (root, nested, `CLAUDE.md` with `AGENTS.md`, a Claude Code `@` import, an `AGENTS.override.md`, a subdirectory shadow, a file over the size cap, a symbolic link), and `expectations.yaml` (`reach_conformance.v1`) gives what each harness's vendor documentation says each file loads in each scenario, or `unknown`. `scripts/reach_conformance.py` checks the expectations against the fixtures, runs `repo reach --format receipt` over them for each harness with a model, credential and CLI present (the rest are recorded as skipped), and merges the per-harness `reach_matrix.v1` JSON into one matrix and one markdown page. `.github/workflows/reach-matrix.yml` runs it nightly and on dispatch, not as a pull-request check, and uploads the matrix as an artifact. The design, the agreement rules and the limits are in `docs/reach-matrix.md`.

dokimi/data/reach-conformance/claude-and-agents/AGENTS.md

@@ -0,0 +1,3 @@
+# Agent guide
+
+These instructions are for the other coding agents.

dokimi/data/reach-conformance/claude-and-agents/CLAUDE.md

@@ -0,0 +1,3 @@
+# Claude instructions
+
+These instructions are for Claude Code.

dokimi/data/reach-conformance/claude-imports-agents/AGENTS.md

@@ -0,0 +1,3 @@
+# Agent guide
+
+Shared rules for every coding agent.

dokimi/data/reach-conformance/claude-imports-agents/CLAUDE.md

@@ -0,0 +1,5 @@
+# Claude instructions
+
+Shared rules live in AGENTS.md.
+
+@AGENTS.md

dokimi/data/reach-conformance/expectations.yaml

@@ -0,0 +1,117 @@
+# Copyright (C) 2026 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+# Vendor-documented state per file and reach scenario; unlisted means unknown (no claim).
+# Sources and scenario meanings: docs/reach-matrix.md.
+schema: reach_conformance.v1
+cases:
+  root-agents:
+    summary: AGENTS.md at the repository root, and nothing else.
+    claude-code:
+      why: With no CLAUDE.md in the working directory or above, Claude Code reads AGENTS.md.
+      files:
+        AGENTS.md: {"cwd=.": loaded}
+    codex:
+      why: Codex checks AGENTS.override.md then AGENTS.md in each directory from the git root to cwd.
+      files:
+        AGENTS.md: {"cwd=.": loaded}
+
+  nested-agents:
+    summary: A root AGENTS.md and a packages/app/AGENTS.md below it.
+    claude-code:
+      why: >-
+        Every AGENTS.md in the working directory and above loads at start-up. A subdirectory's
+        AGENTS.md loads when Claude reads a file there with the Read tool.
+      files:
+        AGENTS.md: {"cwd=.": loaded, "cwd=packages/app": loaded, "read=packages/app": loaded}
+        packages/app/AGENTS.md: {"cwd=.": not_loaded, "cwd=packages/app": loaded, "read=packages/app": loaded}
+    codex:
+      why: >-
+        Codex walks from the git root down to cwd, one file per directory. A directory off that path
+        is not read; the docs do not describe a read-triggered load, so read= is unknown.
+      files:
+        AGENTS.md: {"cwd=.": loaded, "cwd=packages/app": loaded}
+        packages/app/AGENTS.md: {"cwd=.": not_loaded, "cwd=packages/app": loaded}
+
+  claude-and-agents:
+    summary: A root CLAUDE.md beside a root AGENTS.md.
+    claude-code:
+      why: >-
+        AGENTS.md is read only when there is no CLAUDE.md in the working directory or above; the
+        default setting (claude-md-or-agents-md) reads the CLAUDE.md files alone.
+      files:
+        CLAUDE.md: {"cwd=.": loaded}
+        AGENTS.md: {"cwd=.": not_loaded}
+    codex:
+      why: >-
+        Codex checks AGENTS.override.md, AGENTS.md and the project_doc_fallback_filenames list only,
+        and CLAUDE.md is not on that list by default.
+      files:
+        AGENTS.md: {"cwd=.": loaded}
+        CLAUDE.md: {"cwd=.": not_loaded}
+
+  claude-imports-agents:
+    summary: A root CLAUDE.md that imports AGENTS.md with @AGENTS.md.
+    claude-code:
+      why: CLAUDE.md @path imports are expanded and loaded with the file that references them.
+      files:
+        CLAUDE.md: {"cwd=.": loaded}
+        AGENTS.md: {"cwd=.": loaded}
+    codex:
+      why: Codex does not read CLAUDE.md by default, so the import is never followed.
+      files:
+        AGENTS.md: {"cwd=.": loaded}
+        CLAUDE.md: {"cwd=.": not_loaded}
+
+  override-file:
+    summary: A root AGENTS.md beside an AGENTS.override.md.
+    claude-code:
+      why: The Claude Code AGENTS.md rules list AGENTS.override.md among the files it does not read.
+      files:
+        AGENTS.md: {"cwd=.": loaded}
+        AGENTS.override.md: {"cwd=.": not_loaded}
+    codex:
+      why: >-
+        In each directory AGENTS.override.md is used in place of AGENTS.md, and at most one of the
+        two is read.
+      files:
+        AGENTS.override.md: {"cwd=.": loaded}
+        AGENTS.md: {"cwd=.": not_loaded}
+
+  subtree-claude-shadow:
+    summary: sub/AGENTS.md and sub/CLAUDE.md in the same subdirectory.
+    claude-code:
+      why: >-
+        A CLAUDE.md in the working directory loads at start-up. AGENTS.md is not read in a directory
+        that has a CLAUDE.md of its own.
+      files:
+        sub/CLAUDE.md: {"cwd=.": not_loaded, "cwd=sub": loaded, "read=sub": loaded}
+        sub/AGENTS.md: {"cwd=.": not_loaded, "cwd=sub": not_loaded, "read=sub": not_loaded}
+    codex:
+      why: Codex reads sub/AGENTS.md when cwd is sub, and never reads CLAUDE.md by default.
+      files:
+        sub/AGENTS.md: {"cwd=.": not_loaded, "cwd=sub": loaded}
+        sub/CLAUDE.md: {"cwd=.": not_loaded, "cwd=sub": not_loaded}
+
+  large-file:
+    summary: A root AGENTS.md of about 40 KB, above Codex's 32 KiB default.
+    claude-code:
+      why: >-
+        No size limit is documented. The memory page advises under 200 lines per file, which is a
+        target and not a cut-off. So the state is unknown.
+      files: {}
+    codex:
+      why: >-
+        project_doc_max_bytes (default 32 KiB) caps the combined size of the chain. The docs do not
+        say whether a file that crosses the cap is cut, so the state is unknown.
+      files: {}
+
+  symlinked-file:
+    summary: CLAUDE.md is a symbolic link to AGENTS.md.
+    claude-code:
+      why: The docs do not say how a symbolic link named CLAUDE.md is read, so the state is unknown.
+      files: {}
+    codex:
+      why: Codex reads AGENTS.md itself, and the link's name is not one it checks.
+      files:
+        AGENTS.md: {"cwd=.": loaded}

dokimi/data/reach-conformance/guidance.yaml

@@ -0,0 +1,13 @@
+# Copyright (C) 2026 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+# The guidance-only manifest every conformance case is probed with (`repo reach --manifest-file`).
+# AGENTS.override.md is named here so every harness probes it, not only the ones whose profile names it.
+schema: repo_manifest.v1
+id: reach-conformance
+guidance:
+  globs:
+    - "**/AGENTS.md"
+    - "**/AGENTS.override.md"
+    - "**/CLAUDE.md"
+    - "**/CLAUDE.local.md"