RepoCue Documentation

RepoCue Quick Start

Scope

This guide installs RepoCue from a source checkout, initializes repository context, produces the first overview cue, and installs the optional agent skill.

Out of scope: system-wide installation, packaged releases, MCP, and hosted agent configuration.

Prerequisites

Source installation requires GNU Make, Go 1.24 or newer, and the GNU coreutils install and realpath commands. Confirm the required tools before starting:

command -v make
command -v install
make check-tools

See INSTALLATION.md for the complete prerequisite list.

Install RepoCue

From the RepoCue repository root, preview, apply, and verify the default user installation:

make install.dry-run
make install.apply
export PATH="$HOME/.local/bin:$PATH"
make install.check

The executable is installed as $HOME/.local/bin/repocue. See INSTALLATION.md for custom locations, cross-builds, and removal.

Install the Optional Agent Skill

While still in the RepoCue checkout, install the portable skills/repocue/SKILL.md file for Codex:

REPOCUE_CODEX_SKILL_DIR="${CODEX_HOME:-$HOME/.codex}/skills/repocue"
install -d "$REPOCUE_CODEX_SKILL_DIR"
install -m 0644 skills/repocue/SKILL.md "$REPOCUE_CODEX_SKILL_DIR/SKILL.md"

Install the same skill for Claude Code:

REPOCUE_CLAUDE_SKILL_DIR="$HOME/.claude/skills/repocue"
install -d "$REPOCUE_CLAUDE_SKILL_DIR"
install -m 0644 skills/repocue/SKILL.md "$REPOCUE_CLAUDE_SKILL_DIR/SKILL.md"

Start a new agent session after the first installation so the runtime can discover the skill. The skill remains a standalone repository artifact; it is not a plugin and does not install RepoCue itself.

Create the First Cue

Change to the Git repository that RepoCue should describe:

cd /path/to/git-repository
repocue init .
repocue status
repocue cue --view overview --max-tokens 500

The final command prints a structured JSON overview. --max-tokens 500 limits the estimated size of the cue output; it does not set the AI model’s complete context limit.

Ask an Agent

The CLI command may be entered directly, or an agent with the RepoCue skill may receive a natural-language request:

Use RepoCue to inspect the current repository before reading files. Start with an overview limited to about 500 estimated tokens, and inspect files directly only when the cue is incomplete or uncertain.

The agent should run repocue refresh, initialize the repository first when refresh reports that RepoCue is not initialized, and then run:

repocue cue --view overview --max-tokens 500

RepoCue Installation

Scope

This document covers local builds, user installation, cross-builds, local documentation generation, and hosted documentation deployment.

Out of scope: system-wide installation, package-manager publication, and release signing.

Prerequisites

Check the build tools:

make check-tools

Build and Verify

Run the normal verification path and build both local binaries:

make check
make build

Generated binaries are written below build/bin/. The default build sets CGO_ENABLED=0.

The primary CLI can also be built for the supported distribution targets:

make build.linux-amd64
make build.windows-amd64

Cross-build outputs are written below build/cross/.

User Installation

The default destination is $HOME/.local/bin/repocue. Installation does not require sudo.

Preview, apply, and verify the installation as separate operations:

make install.dry-run
make install.apply
make install.check

If $HOME/.local/bin is not in PATH, install.check reports the mismatch instead of treating the installed file as active. install.apply still completes the file installation and prints a warning so PATH activation and verification remain separate steps.

Activate the default installation path in the current shell, then verify it:

export PATH="$HOME/.local/bin:$PATH"
make install.check

Persist the same PATH entry through the shell configuration used by the local account.

Override the installation prefix without changing tracked files:

make install.dry-run INSTALL_LOCATION="$HOME/.local/repocue"
make install.apply INSTALL_LOCATION="$HOME/.local/repocue"
export PATH="$HOME/.local/repocue/bin:$PATH"
make install.check INSTALL_LOCATION="$HOME/.local/repocue"

Persistent site overrides may be placed in CONFIG_SITE.local or configure/CONFIG_SITE.local. These files are ignored by Git.

Removal

Only the executable at the configured destination is removed:

make uninstall.dry-run
make uninstall.apply
make uninstall.check

RepoCue cache data is not removed by the uninstall target.

For a custom installation prefix, pass the same INSTALL_LOCATION to every removal operation:

make uninstall.dry-run INSTALL_LOCATION="$HOME/.local/repocue"
make uninstall.apply INSTALL_LOCATION="$HOME/.local/repocue"
make uninstall.check INSTALL_LOCATION="$HOME/.local/repocue"

Documentation

Build the local mdBook site under docs/book/:

make docs.build

Remove generated documentation output:

make docs.clean

GitHub Pages

The .github/workflows/pages.yml workflow builds the mdBook site in the jeonghanlee/mdbook container and deploys docs/book/ to GitHub Pages. It runs when relevant files change on master and may also be started manually.

Before the first deployment, configure the repository in GitHub:

1. Open Settings and select Pages.
2. Under Build and deployment, set Source to GitHub Actions.
3. Run the Deploy mdBook to GitHub Pages workflow or push a matching change to master.

Deployment is complete when the workflow’s Deploy to GitHub Pages job passes and reports the site URL.

Direct Go Workflow

The Makefile is a convenience layer over standard Go commands:

go test ./...
CGO_ENABLED=0 go build -trimpath -o repocue ./cmd/repocue

The resulting ./repocue executable is separate from the Make-managed build/ directory.

RepoCue CLI Reference

Scope

This document covers the current RepoCue CLI commands and their Makefile build wrappers.

Out of scope: MCP transport, production structural parsing, checkpoints, pruning, and filesystem watching.

The examples below assume that an installed repocue executable is available in PATH. From a repository checkout, run make build.repocue and replace repocue with build/bin/repocue. A direct Go build described in INSTALLATION.md instead produces ./repocue.

Help

List every command with a one-line summary:

repocue help

Show the synopsis, summary, and flag defaults of one command:

repocue help cue
repocue cue --help

Help output is plain text on stdout with exit code 0. Running repocue without a command prints the same usage on stderr with exit code 2. Every other failure exits with code 1 and writes a single-line JSON error as the first line of stderr; an unknown command additionally prints plain-text usage guidance after that line.

Repository State

Initialize the current Git repository with a deterministic full baseline:

repocue init .

Inspect the live Git basis and cached RepoCue state:

repocue status

Refresh changed tracked files and publish a new snapshot only when indexed state changed:

repocue refresh

Start a new epoch with a full baseline while retaining the superseded epoch:

repocue rebaseline --label milestone:first-prototype --reason manual

Except for the optional path accepted by init, state commands accept flags only. Use --repository PATH where applicable and --cache-dir PATH to override the normal cache location.

At an ordinary repository root, the CLI reuses a validated location.json beside the SQLite database. A warm overview cue, status, or refresh needs three Git calls; a missing or changed location hint requires discovery again. Subdirectories, linked worktrees, and special Git configuration use the normal discovery path. Location-cache write failures warn on stderr after the command result without changing the JSON result or canonical snapshot state. If the command fails, its JSON error remains the first stderr line, followed by the warning.

Keep files and Git state unchanged while a command scans the repository. RepoCue captures the scan’s Git basis once, including when status or cue checks freshness. If an editor or another process writes during the scan, rerun refresh after it finishes before relying on the result.

Cues

Generate a compact overview within an estimated token budget:

repocue cue --view overview --max-tokens 500

Generate a file-level repository-state delta from an earlier snapshot:

repocue cue --since snapshot-000001 --max-tokens 500

Experimental evaluation views remain available for measured comparisons:

repocue cue --view ranked --max-tokens 500
repocue cue --view provenance --path internal/ --max-tokens 500

Ranked facts are emitted only when the live repository still matches the stored snapshot. A provenance cue reports matched_files and adds a provenance_files_omitted warning when the token budget omits file records.

Metrics and Evaluation

Read recorded baseline, refresh, and cue measurements:

repocue metrics

Run the model-neutral repository evaluation without external agent runners:

repocue evaluate --repository . --max-tokens 500

External runner and M2 experiment contracts are documented in EVALUATION.md. The repocue-codex-runner binary is an evaluation adapter and is not installed by the user installation target.

Run the five-condition M2 harness without an external agent runner:

repocue evaluate-m2 \
  --repository . \
  --oracle-tool tools/evaluation/structural-oracle.bash \
  --output-directory /tmp/repocue-m2-reports \
  --temporary-root /tmp/repocue-m2-work \
  --max-tokens 500

The output parent receives one generated report-set directory containing all five condition reports. Output and temporary paths must be outside both the evaluated worktree and its Git directory. RepoCue creates either parent when it does not exist.

Makefile Wrappers

Build and verify the CLI:

make check
make build.repocue

Preview and apply user installation:

make install.dry-run
make install.apply
make install.check
make uninstall.dry-run
make uninstall.apply
make uninstall.check

Quantitative Reports

Read a report after initializing the repository; no agent is launched:

repocue report --repository .
repocue report --repository . --window 30d --format markdown
repocue report --repository . --consumers 7
repocue report --repository . --as-of 2026-09-01T00:00:00Z

Defaults are JSON, a 30-day UTC window, and 1, 2, 3, 5, and 10-consumer scenarios. Positive --consumers N adds an explicit scenario. No profile means maintenance only. One eligible profile is selected automatically; multiple profiles require --profile <calibration-id> and otherwise suppress projections. An unknown profile or missing/tampered selected artifact is an error.

--as-of accepts a non-future RFC3339 UTC instant. State and binding observations must be strictly before it. Metric recording time governs activity and full epoch maintenance; it is not database publication time. Current validation and DB size remain separate current observations. Repeating historical results requires the same DB/evidence basis; later retained observations can change the result. Missing historical content evidence never comes from today’s state.

An unchanged verified binding is measured_reference; a compatible later snapshot is estimated with file/byte/language drift. Stale tracked state, a new epoch, incompatible contract, or same-snapshot untracked-content change makes the profile not_applicable. Report does not refresh. Ordinary refresh cannot repair that untracked-content mismatch; renewed authorized evidence is needed. Quality is dated source evidence, not a current assessment.

Import External Calibration

Use a complete compatible direct/basic set from an authorized experiment. Substitute your own external paths:

reports=/tmp/repocue-pairs
evidence=/tmp/repocue-pairs/calibration-evidence.json
repocue calibration import --repository . --reports "$reports" --evidence "$evidence"

Optional --assessments /absolute/assessment-directory validates the qualitative files named in the evidence. Otherwise semantic quality is not assessed. Import binds source content to the local current epoch/snapshot, not to a coincidentally equal ID in the evaluator’s temporary DB. Producer provenance and exact digests are mandatory; historical values are never filled from the current binary. The result contains calibration ID, relative path, and digest. Reimport is idempotent.

Direct/basic preparation needs no structural oracle:

repocue evaluate-m2 --repository . --conditions direct,basic --output-directory /tmp/repocue-pairs

Without --runner this emits two dry-run reports, which cannot calibrate agent savings. An authorized runner uses the existing --runner and --task-file contract. Output and temporary workspace must remain outside the evaluated worktree and Git directory. Import from the generated set directory and its calibration-evidence.json, not the output parent. Multiple pairs require one evidence document naming selected reports and contemporaneous records. Import and report never implicitly run a model.

Atomic Publication Wrapper

Report writes stdout and returns nonzero on failure. Do not redirect over the last successful report. Save this optional Bash script as /home/example/bin/repocue-report.bash, replace its four absolute paths, and make it executable. It requires Bash, Git, flock, mktemp, mkdir, and mv. It creates only its external output directory and retains failed drafts. Keep the repository idle during execution. The example installs nothing.

#!/bin/bash
set -euo pipefail
export PATH=/usr/local/bin:/usr/bin:/bin
readonly repocue_binary=/home/example/.local/bin/repocue
readonly repository=/srv/project
readonly cache=/home/example/.cache/repocue
readonly report_dir=/home/example/reports/repocue
umask 077
mkdir -p -- "$report_dir"
exec 9>"$report_dir/report.lock"
flock -n 9 || exit 75
report_tmp=$(mktemp "$report_dir/.report.XXXXXXXX")
trap 'status=$?; if (( status != 0 )); then printf "Failed draft: %s\n" "$report_tmp" >&2; fi' EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
"$repocue_binary" report --repository "$repository" --cache-dir "$cache" --format markdown >"$report_tmp"
test -s "$report_tmp"
mv -f -- "$report_tmp" "$report_dir/current.md"

After verifying the wrapper manually, a user crontab entry can run it at 06:00:

0 6 * * * /home/example/bin/repocue-report.bash

An alternative user systemd service and timer use the same lock and publisher:

# repocue-report.service
[Unit]
Description=Produce a RepoCue quantitative report
[Service]
Type=oneshot
WorkingDirectory=/srv/project
ExecStart=/home/example/bin/repocue-report.bash

# repocue-report.timer
[Unit]
Description=Run the RepoCue report daily
[Timer]
OnCalendar=daily
Persistent=true
Unit=repocue-report.service
[Install]
WantedBy=timers.target

Use cron or the timer, not both. Scheduling, permissions, retention, and activation remain operator-owned. A held lock returns 75; command failure leaves current.md unchanged. JSON and Markdown contain the same calculation, classifications, and limitations. Markdown includes complete canonical JSON as a data appendix.

Task context and evaluation

Task delivery requires a tracked declaration and explicit applicability inputs. The task contract defines pins, range bytes, and whole units.

Task flags fail with legacy views. Task mode rejects --since and --path, including explicitly empty values. Refresh-needed state fails. A matching dirty snapshot is valid. Source failures and mandatory overflow produce no successful cue stdout.

For the tracked example, generate a discovery cue with original README text:

context=docs/task-context.example.json
repocue cue --view task --context-file "$context" --task-kind discovery --target internal/cue --max-tokens 5000

Use an initialized idle checkout containing the committed example declaration. The result has required ID repository-context and a full-file README digest.

Default task evaluation prepares both contexts without an external agent:

repocue evaluate-task --task-file <task_file> --output-directory <external_directory>

<task_file> is task-benchmark-1 JSON. <external_directory> is outside the evaluated checkout. Preparation uses the maintained cache and refreshes it; an uninitialized cache fails. The task file selects its declaration, targets, prompt, policy, and common budget.

The runner receives an exact task-runner-1 request through REPOCUE_TASK_RUNNER_CONFIG and REPOCUE_EVAL_SCHEMA. The shipped runner dispatches this version separately from legacy evaluation. Real provider support and paid settings require the experiment preflight.

A unique external pair directory retains partial and completed records. A failed pair exits nonzero and can emit its evidence report on stdout. A failure never authorizes another invocation, retry, or continuation.

Summarize retained attempts without launching a process:

repocue evaluate-task summary --input-directory <external_directory>

Optional --assessment-file joins bound source-backed assessments. Summary retains wrong/incomplete attempts, known/unknown metric coverage, paired differences, and independent delivery/correctness/compliance fields. Task evidence cannot enter calibration import.

Explicit prompt-cache evaluation

evaluate-cache prepare freezes original task context and bounded Claude request settings without a key or provider request. run explicitly sends one selected step. summary reads retained artifacts without a process or network request. None of these commands runs an agent tool or repository command from a model answer. The prompt-cache reference defines all flags, examples, supported profiles, evidence, and measurement limits.

RepoCue Core Architecture

Scope

This document defines the component boundaries and data flow for the accepted Go core, the M2 structural-context experiment, and quantitative reporting.

Out of scope: MCP, production source parsing, semantic embeddings, LLM processing, filesystem watching, checkpoints, pruning, and retention-policy enforcement.

Components

cmd/repocue owns process startup. internal/app parses CLI requests and coordinates the concrete repository, storage, snapshot, cue, and metrics packages. The repository package runs Git and reads tracked working-tree files. The storage package owns SQLite schema and transactions. The snapshot package computes repository-state semantic file changes. The cue package selects and serializes agent-facing JSON within a token estimate. The metrics package contains measurement rules shared by commands. The evaluation package measures the shipped repository, storage, and cue paths and optionally invokes external agent runners through a versioned JSON contract.

SQLite driver selection is isolated in internal/storage. The first slice uses modernc.org/sqlite through database/sql because it is CGo-free and can be distributed in the RepoCue executable.

Data Flow

CLI request
  -> discover Git repository
  -> capture Git basis once (repository remains unchanged during the scan)
  -> scan all tracked files or changed tracked files
  -> commit epoch, snapshot, file state, delta, and run metrics in one SQLite transaction
  -> project deterministic JSON

Repository content is hashed as a stream while retaining at most the first 8 KiB for binary classification; file size does not determine scanner memory. Content is not stored. Ignored files are excluded. Non-ignored untracked paths affect dirty-state metadata but their content is not indexed in this slice.

Git index entries marked assume-unchanged or skip-worktree are rejected in this slice because Git may hide working-tree changes for those paths and RepoCue could not claim current freshness.

Bootstrap Decisions

• Repository identity uses the first 96 bits of the resolved repository root’s SHA-256 digest. Moving a checkout creates a distinct local cache.
• Public epoch, snapshot, delta, and file identifiers are text values and do not expose SQLite row IDs.
• A snapshot is created only when indexed Git or file state changes. A no-op refresh records metrics and retains the existing snapshot.
• Manual rebaseline creates a new active epoch and marks the former epoch superseded without deleting its data.
• Semantic delta operations are file-level until a parser is introduced.
• File operations are repository-state semantic deltas. They do not claim code-symbol, dependency, or document semantics.
• Freshness is current for a clean indexed state, dirty-but-indexed when the indexed tracked state matches a dirty working tree, and refresh-needed when the live state differs from the current snapshot.
• Token estimation is ceil(serialized UTF-8 bytes / 4). It is explicitly an estimate and is stored with the exact output byte count.
• SQLite schema version 3 adds calibration references. Versions 1 and 2 migrate transactionally; read-only reports accept versions 2 and 3.

Transaction Boundary

Repository scanning happens before the SQLite write transaction. Files and Git state must remain unchanged for the duration of each scan. The scanner captures one Git basis and records its initial observation time; it does not recapture the basis after scanning or revisit every scanned path. Regular-file reads retain their local before/after metadata check, but this is not a guarantee against repository-wide concurrent mutation.

The database transaction verifies the expected current snapshot before publishing the new snapshot. An interrupted write therefore cannot leave a partially-current snapshot. Changes between scans are still detected by a new Git basis and changed-file scan. After a concurrent filesystem edit, rerun refresh when the repository is idle.

Each full or incremental scan normally uses three Git commands: porcelain v2 status supplies HEAD and changed paths; symbolic-ref --quiet --short HEAD supplies the branch; one tagged index listing supplies file entries, the index digest, visibility flags, and conflict checks. The index digest preserves the untagged ls-files --stage -z byte format, so existing snapshots remain comparable. Branch identity preserves Git’s short symbolic-ref format, including heads/main when a main tag creates ambiguity. A branch literally named (detached) remains distinct from detached HEAD. Status disables optional index writes.

CLI repository discovery normally adds one call. At an ordinary repository root, a valid location hint removes that call: status, refresh, or an overview cue then uses three calls instead of four. A gitlink requires two additional diff queries to preserve configuration-sensitive submodule behavior. A repository or Git-directory path containing a newline requires two additional discovery queries because rev-parse does not delimit its path output with NUL. Counts cover Git processes invoked by RepoCue, not additional children started internally by Git. Ranked cues and evaluation may perform additional context and state checks.

CLI Location Cache

The CLI stores a disposable location.json next to state.db, under the same cache-root selection rules. It is written only after Git confirms that the requested path is the ordinary repository root with a real .git directory. Reuse checks the canonical root, Git-directory metadata, local configuration and HEAD contents, and Git executable path/metadata. It never reuses a branch, HEAD value, dirty-state answer, or freshness result; scans still query live Git.

Missing, malformed, oversized, or mismatched hints cause a new Git discovery. Moves produce a different root identity; changed local configuration or Git layout invalidates reuse. Subdirectory requests, linked worktrees, separate Git directories, configuration includes/extensions, explicit worktree configuration, and Git environment overrides retain Git discovery. Trace and pager variables do not disable reuse. Eligibility is conservative rather than a second Git configuration parser. The direct repository API and evaluation harness remain uncached.

Hint replacement uses a private temporary file and rename. Read failures are cache misses; write failures produce a warning on stderr while the successful Git discovery remains usable. Warnings are buffered until command completion; if the command fails, its JSON error precedes any warning. The hint is not canonical state, does not change the SQLite schema, and may be removed without losing snapshots. Its file reads and discovery cost are outside the existing scan-only metrics.

Evaluation Boundary

The evaluation harness creates its SQLite state in a temporary directory and does not modify the evaluated repository. A repository-only probe measures the full baseline, no-op update, cue projection, content bytes read, file count, Git command count, database size, and wall duration.

Optional direct and assisted runners are separate executables. Runner-specific tokenizers and agent event formats remain outside the core packages. The harness verifies that each runner leaves the repository state unchanged.

Facts derived from live Git commands are accepted only when scans before and after the read match the persisted snapshot. Ranked cues fail instead of combining an older snapshot envelope with facts from a newer repository state.

repocue-codex-runner is the first adapter. It invokes a fresh ephemeral Codex non-interactive run, consumes the JSONL event stream, classifies observable commands, and returns one versioned model-neutral runner observation. The benchmark package scores deterministic Git facts after the harness verifies the repository basis. Semantic answers remain available for a separate qualitative assessment.

M2 Experiment Boundary

M2 compares five fixed conditions rather than introducing a general extension framework:

direct
placebo
basic
ranked
structural-oracle

One baseline and one no-op refresh prepare a shared maintained state. Each condition receives a fresh external runner process. All assisted conditions use the same instruction and context budget. The direct condition receives no RepoCue context.

M2 output and temporary paths must be outside the evaluated worktree and Git directory. The harness validates all five conditions before publishing a report-set directory with one atomic rename. A failed condition therefore exposes no part of its five-report set and the same run can be retried.

The structural oracle is an evaluation tool, not a core backend. A Bash executable extracts conservative symbol candidates from tracked Bash and Python files. Go parses its tab-separated records, serializes JSON safely, and composes the structural condition within the same token estimate as the ranked condition. M2 adds no parser module, structural database table, AST, call graph, or persistent structural index.

The runner contract records every observed Codex turn.completed.usage event. Command classification and the sum of current sizes for explicitly named repository paths are derived measurements. That byte value is named named_file_size_proxy_bytes; it is not observed filesystem I/O. The harness rejects negative or internally inconsistent metrics, invalid measurement status values, mismatched repository or benchmark metadata, and condition sets that do not share identical runner metadata.

Deployment Constraint

The default build remains CGo-free. Linux static linking and Windows amd64 cross-building are release constraints. A future structural backend must be measured against those constraints before it becomes a production dependency.

Quantitative Reporting Boundary

internal/evidence defines external calibration provenance and contained, digest-checked file references. repository.CaptureEvidence adds streamed non-ignored untracked content to Git and tracked-file evidence without changing core refresh scope. Unreadable entries prevent a complete capture; symlinks contribute target text, not target contents.

Explicit evaluate-m2 --conditions direct,basic measures the shipped cue executable and supplies its captured stdout to the assisted runner. It records wall duration, cache/hint state, executable digest, and digest-linked Git Trace2 process sessions. Builder duration is a separate diagnostic. This path needs no oracle; the default five-condition experiment remains unchanged.

internal/reporting validates complete compatible external pairs, recomputes the five deterministic Git facts, optionally joins qualitative assessments, and publishes compact numeric calibration. Raw answers, prompts, scoring basis, and assessment narratives remain external. SQLite serializes publication and rechecks the expected local snapshot. A failed transaction can leave an unreferenced artifact, never a trusted partial reference.

Reports read state, history, and references in one read-only transaction, then validate live content. They never refresh, migrate, write cue metrics, invoke an agent, or store stdout. Source snapshot IDs are provenance, not local DB identity. Exact content matches are measured references; compatible later snapshots are estimates. Epoch/contract or same-snapshot untracked-content mismatches suppress projections. Quality remains dated calibration evidence.

Reuse arithmetic is pairwise and unit-specific. Historical state uses observation time; activity and full-epoch maintenance use metric recording time. Neither proves SQLite publication time. Missing measurements and ambiguous legacy zeros cannot become observed savings. See ADR 0002 and Evaluation.

Task context and evidence boundary

internal/taskcontext strictly parses tracked declarations, selects explicit task/path applicability, and streams pinned original source ranges. internal/cue assembles the complete required task envelope before optional whole units. internal/app validates the live snapshot before and after extraction. SQLite stores existing file metadata and cue metrics; it stores no instruction text and receives no task schema migration.

internal/taskbenchmark binds selector-derived required IDs and original references to task-specific outcomes. It separates actual provision, verification completion, correctness, and semantic assessment. internal/codexadapter captures task stdin, the digest-checked answer schema, invocation, raw streams, and only supported usage/completion/output fields through a separate exact-version route. The provider receives the captured attempt-local schema. Summary checks it against the frozen pair schema, runner request, observation, and invocation.

internal/evaluation prepares actual overview/task CLI outputs, creates external attempts before model launch, checks pre/post content fingerprints, and retains failures. Summary reads retained files without starting a process. Digest consistency and frozen policy guard paired descriptive comparisons; they are not provider signatures or permission enforcement.

Task execution is opt-in and bounded to one pair per invocation. Local fixtures replace only external Codex. Paid execution and evidence capability preflight are separate. See Task contracts and ADR 0003.

RepoCue Data Model

Scope

This document defines core repository state and quantitative-reporting data.

Out of scope: checkpoint tables, pin state, pruning metadata, and retention policy.

State Hierarchy

repository
  -> epoch
       -> baseline snapshot
       -> refresh snapshot
            -> semantic delta from its parent

Exactly one epoch is active for a repository. A rebaseline changes the active epoch and keeps the preceding epoch as superseded.

Stable Public IDs

• Repository: repo-<root-digest>
• Epoch: epoch-000001
• Snapshot: snapshot-000001
• Delta: delta-000001
• File entity: file:<repository-relative-path>
• Calibration: calibration-<sha256>

Sequence values are allocated transactionally and stored as explicit text identifiers. SQLite internal row IDs are not part of the public model.

The CLI may keep a versioned location.json beside state.db. This disposable hint contains the verified root, Git directory, and a validation digest, not snapshot data. It does not alter the SQLite schema or identity rules and is not included in the SQLite database-size measurement.

Snapshot Basis

Each snapshot stores branch, HEAD, staged paths, unstaged paths, untracked paths, dirty state, a Git-state digest, a repository file-state digest, and an observation time. HEAD and working-tree state remain separate.

The observation time identifies the initial Git basis capture. Repository files and Git state are assumed unchanged during each scan. This assumption does not weaken the SQLite transaction or expected-current-snapshot checks.

File State

Each tracked path records its stable entity ID, Git index mode and object ID, working-tree mode, existence, byte size, SHA-256 content digest, file type, language, document classification, and working-tree state. File contents are never stored.

Repository-State Semantic Delta

The first slice emits file and repository operations that describe meaningful changes in the indexed repository state:

• file.added
• file.deleted
• file.restored
• file.content_changed
• file.metadata_changed
• file.state_changed
• repository.branch_changed
• repository.head_changed
• repository.working_tree_changed

Delta items store optional before and after values so a future retention or checkpoint implementation can reference immutable snapshots without changing the public state model.

One file path has one operation in a delta. When content and metadata change together, the operation remains file.content_changed and its cue projection also includes every changed metadata field so the concurrent change is not lost.

These operations are not code-symbol semantic deltas. Later parsers may add separate symbol, dependency, and document operations without changing the existing file-level operation names.

Measurement

Operation runs store state-preparation duration, scan duration, Git command count, files scanned, bytes scanned, changed-file count, epoch, and snapshot. Cue runs store view, token budget, exact output bytes, and estimated output tokens. Database size is measured from the SQLite file at report time.

Evaluation reports remain versioned JSON artifacts rather than canonical repository state. They distinguish observed from not_observed measurements and keep tokenizer-specific token counts separate from the runtime byte-based estimate.

Real-agent reports additionally distinguish derived and estimated values. They retain runner metadata, Codex token usage, command observations, the final structured benchmark answer, deterministic Git-fact scores, and projected reuse totals. These artifacts are not persisted in the repository state database.

M2 condition reports share a maintenance ID so baseline and refresh cost can be counted once across conditions and consumers. Each report records the condition, run index, repository state fingerprint, RepoCue snapshot, cue schema and size, runner observation, and limitations. A complete five-report set is staged outside the evaluated repository and published as one directory only after every condition and repository-state check passes.

M2 does not change the SQLite schema. Structural oracle candidates exist only while composing an evaluation cue. A future structural index must use stable entity IDs and content-digest keys, record parser backend and version provenance, and re-analyze only changed source files. Retention behavior for such an index belongs to the later storage-lifecycle design.

Calibration And Reporting

Schema 3 adds calibration_references: calibration ID, repository ID, local epoch and snapshot, relative artifact path, SHA-256 digest, binding observation time, content fingerprint and algorithm, contract digest, model, and benchmark. Existing state and measurement rows are preserved. There are no new measurement-history or structural tables.

Immutable calibrations/<id>.json files beside state.db use repocue/calibration-1. They retain numeric paired samples, source-report digests and snapshot IDs, producer/cue/runner contracts, correctness outcomes, optional qualitative scores and dates, local binding, and limitations. Identity excludes import time; reimport returns the original observation. Missing or modified referenced files are errors, not usable profiles.

External repocue/calibration-evidence-1 names reports, cue stdout, Git events, scoring basis, and assessments using relative paths and digests. It preserves the original evaluation fingerprint separately from repocue/content-evidence-1, which combines Git status/index, tracked state, and sorted non-ignored untracked path/kind/mode/content digests. Absolute evaluated paths and raw responses are not copied into calibration. Existing SQLite repository-root metadata remains unchanged.

repocue/savings-report-1 is stdout-only. Measurements identify classification, unit, accounting boundary, and unavailable values. Statistics retain pair values, medians, ranges, counts, and unknown coverage. JSON and Markdown share one calculation result.

State selection uses the greatest observation strictly before cutoff, with snapshot sequence resolving ties. Binding selection uses its evidence observation. Activity uses [start, cutoff) recording times; maintenance uses all baseline/rebaseline and refresh rows in the selected epoch before cutoff, including pre-window rows. These are not publication-time claims.

Version-1 migration supplied zero defaults for scan duration and Git count. Without independent provenance these zeros remain not_observed, even in a version-2 DB. Valid zero scanned bytes remain zero. Partial known-only statistics never replace full totals, trends, maintenance, or break-even. DB size is a dated current observation; historical size and routine cue-runtime trends have no retained measurement path.

Independent task context values

repocue/task-context-1 is an author-owned tracked declaration, not a SQLite table. Each item has stable ID/kind, explicit task/path dimensions, required status, primary source, and supporting check references. A source identity hashes canonical path, expected full-file digest, and inclusive range. The declaration digest belongs to its maintained snapshot.

repocue/task-cue-1 contains repository/epoch/snapshot/basis/freshness, declaration identity, normalized request, required IDs, whole delivered items/sources, extracted text digests, and optional omission accounting. Source text is transient. Existing cue metrics record view task.

Benchmark, answer, runner, and evaluation have independent task version 1. External evaluation values contain frozen task/policy/rate/schema digests, settings, content fingerprints, full CLI costs, raw-artifact digests, and every attempt. Attempt journals distinguish started, completed, failed, invalid, and cancelled. Pair reports bind the actual answer schema with output_schema_digest. Runner requests require that digest; observations retain the captured digest or null when schema capture is unavailable. Each attempt stores the schema bytes passed through its captured invocation.

Summary inventory keeps delivery, correctness, compliance, metric status, eligibility, and errors separately. Per-metric paired coverage and differences remain separate from a gated verdict. Assessments bind exact task/policy, attempt/answer, source basis, assessor, and rubric. No task result is a calibration reference. See Task contracts.

RepoCue Evaluation

Objective

The evaluation system measures whether maintained RepoCue context reduces the total resources required for an agent to understand a repository’s current state. Core packages remain independent of a specific agent, model, or tokenizer.

M2 Conditions

M2 uses five fixed conditions under the same repository state, working directory, model, reasoning setting, sandbox, benchmark, output schema, and maximum estimated context tokens:

All assisted conditions receive the same instruction: use supplied context first and inspect the repository whenever it is incomplete, uncertain, or insufficient. They are not told to avoid fallback reads.

Experimental Ranked Selection

The ranked and structural-oracle conditions share the same deterministic ranked-content fitter. This policy is experimental and does not change the frozen basic condition.

Ranked content admits at most 12 document paths. Root README, AGENTS, ARCHITECTURE, and CHANGELOG files rank ahead of nested README files; remaining ties use path depth and bytewise path order. Directory candidates are ordered as depth one followed by depth two. Budget fitting removes depth-two directories first, then low-ranked documents, Makefile targets, recent commit subjects, and finally depth-one directories before entry points or structural candidates. The four-repository M2 corpus must retain all depth-one directories at the 500-token experiment budget.

Preparation and Isolation

The harness prepares one deterministic full baseline, one no-op refresh, and all condition contexts before starting an agent. Every report carries the same maintenance ID and RepoCue snapshot for that prepared state. Baseline and refresh cost are counted once in reuse analysis.

Each individual scan assumes files and Git state stay unchanged until that scan returns. The initial Git basis is captured once. Separate checks around external agent and oracle execution remain required, because those processes can span repository state transitions between scans.

Live Git facts and structural-oracle output are bracketed by snapshot checks. The harness stops if the repository no longer matches the maintained snapshot. The output directory and temporary workspace parent must be outside the evaluated worktree and Git directory so experiment artifacts cannot change a later condition.

Each condition starts a fresh external runner process. The harness captures a state fingerprint before and after the process and rejects a run that modifies the repository. All five reports are written under a temporary report-set directory and published by one directory rename after every condition passes. A failed run exposes no part of the set and can be retried with the same index.

The observed experiment uses three runs for every repository and condition. A complete comparison group therefore has 15 reports per repository. Per-repository results are reported before any aggregate.

Versioned Contracts

• Condition report: repocue/evaluation-4
• External runner observation: repocue/evaluation-runner-4
• Benchmark: repository-state-v2
• Benchmark answer: repocue/benchmark-answer-2
• Experimental cue: repocue/cue-2
• Qualitative assessment: repocue/qualitative-assessment-2

Each published directory is named by repository, model, run index, and maintenance ID. Files within it are named by repository, condition, model, and run index. They record the supplied repository path and resolved root, exact HEAD, state fingerprint, RepoCue snapshot, condition order, cue bytes, estimated cue tokens, runner metadata, token components, commands, final response, and limitations.

The runner observation contract requires ordered usage events and one final JSON object. Runtime validation rejects negative values, token or command totals that contradict their observations, unknown or inconsistent status values, basis metadata mismatches, and runner metadata drift across conditions.

New executions require version 4. Calibration import also accepts unchanged evaluation-3 reports with their matching evaluation-runner-3 contract. Import selects the declared JSON Schema and runtime rules; unknown versions, mixed report versions within one selected set, mismatched report/runner versions, and incomplete version-3 token observations are rejected.

Legacy reads preserve source bytes, digests, versions, and declared values. They cannot determine whether a historical zero originated from an omitted Codex field. Legacy report readability does not establish applicability: producer, repository, cue, and evidence compatibility checks still apply.

Codex Adapter

repocue-codex-runner invokes a fresh ephemeral Codex non-interactive run in JSONL mode with ignored user configuration and rules, read-only sandboxing, the selected model and reasoning setting, and benchmark output schema. Completed-turn JSONL events expose available usage counters [1]; they do not expose the CLI’s complete hidden context or provider request sequence.

Adapter version 3 preserves every turn.completed event, including a turn whose usage object is absent, null, or empty. Each token counter is optional: an omitted or null value means unknown; an explicit zero remains observed. The output omits unknown counters and requires not_observed for each unknown aggregate. Version-4 readers also accept explicit JSON null.

A counter’s aggregate is available only when every completed turn supplies that counter. Partial values remain in the ordered usage events but never masquerade as a complete run total. Input and output determine total tokens; missing cached or reasoning values do not erase a complete input/output total. Cached and reasoning counts are subsets and are never added to total tokens. Negative values, invalid event order, cached counts exceeding a known input count, and integer overflow are errors. A stream with no completed turns is an error. A completed turn without usage can still retain commands, duration, the final response, and correctness. Only comparisons and projections requiring missing measurements become unavailable.

The adapter distinguishes measurement sources:

observed
derived
estimated
not_observed

Token events, completed tool events, execution duration, and the final agent response are observed from the process and event stream. Git/search command classes and explicit path names are derived from command text.

named_file_size_proxy_bytes is the sum of current file sizes for repository paths explicitly visible in classified command text. The assisted form is fallback_named_file_size_proxy_bytes. These are derived proxies. They do not measure bytes transferred by Git, directory traversal, kernel cache behavior, partial reads, repeated reads, or actual filesystem I/O.

Benchmark and Scoring

Repository-state v2 preserves the deterministic Git questions from v1 and adds project-defining symbols, signatures, owners, and relevance. The deterministic scorer compares branch, full HEAD, dirty state, tracked change paths, and untracked paths with the snapshot basis.

Purpose, architecture, documentation, recent changes, structural completeness, and uncertainty handling use a separate blinded qualitative assessment. The assessment records assessor identity, response ID, repository HEAD, state fingerprint, run index, condition, scores, and evidence. Qualitative values are not presented as deterministic ground truth.

Structural Oracle

The M2 oracle uses Bash, Git, grep, awk, and sort. It extracts conservative Bash functions and source relationships plus Python classes, functions, methods, signatures, and imports. Production src/**/*.py candidates rank before tests/**/*.py.

The oracle has no ctags, Python runtime, Tree-sitter, or parser dependency. It does not infer call graphs, data flow, or references. Unsupported records are omitted and reported as limitations.

Reuse Analysis

Reuse projections cover 1, 2, 3, 5, and 10 independent consumers and keep these values separate:

• one-time baseline cost;
• incremental refresh cost;
• per-agent cue cost;
• per-agent fallback discovery cost.

M2 experiment reuse totals are derived. Estimated cue tokens remain the fast runtime estimate ceil(serialized UTF-8 bytes / 4). Measured tokenizer- specific counts are separate fields.

M2 does not claim success before real condition reports and blinded qualitative assessments exist. Dry runs verify contracts and execution paths; they are not agent evidence.

Quantitative Reporting

Routine repocue report separates recorded maintenance from calibration-based agent projections. It runs no agent, model, or tokenizer. Without calibration it reports maintenance and unavailable agent evidence, not savings. Local M1 adds no real-agent result: its synthetic external-runner fixtures validate software behavior only.

Direct/basic preparation times the shipped cue CLI through exit and complete stdout capture, then delivers those exact bytes to the basic runner. Evidence records executable/revision, arguments, cache/hint state, output digest, times, and digest-linked Git Trace2 events. Builder time remains diagnostic; setup and pre/post isolation captures are separate experiment overhead. Import rejects a cue observation that finishes after the selected assisted pre-run capture; matching bytes alone do not establish pre-agent delivery.

Import requires complete pairs with identical repository and runner contracts and verifies content-sensitive evidence against the checkout and maintained snapshot. One pair is exploratory; at least three are descriptive, never a significance claim. Unsupported legacy provenance is rejected; optional missing cue cost or scoring stays unavailable. Raw answers and narratives stay external. Estimated source agent costs remain labeled diagnostics. Only observed or derived agent costs enter paired calibration statistics and reuse arithmetic; an excluded estimate increases unknown coverage only for its measurement.

The existing scorer checks branch, HEAD, dirty state, tracked changes, and untracked paths independently of qualitative assessment. Incorrect valid responses remain in efficiency samples. Optional assessment-2 scores are digest-joined to responses and retain assessor and known dates. Missing dates are not inferred from file timestamps; no score assesses a later snapshot.

For pair i, D_i is direct agent cost, A_i assisted agent cost, Q_i comparable full cue CLI cost, and H recorded local epoch maintenance:

direct_i(N) = N * D_i
assisted_i(N) = H + N * (A_i + Q_i)
saving_i(N) = direct_i(N) - assisted_i(N)

Calculate per pair before medians, ranges, and percentages. Paired [100, 200, 300] and [90, 1, 299] have median difference 10, not the difference of medians, 110. Missing pairs have per-metric coverage. Future 1, 2, 3, 5, and 10-consumer scenarios are estimated even at an exact measured reference. --consumers N adds an explicit scenario; cue counts are not users.

Agent tokens already include supplied context, so additional cue tokens are zero by accounting definition; estimates are not added again. Deterministic core H has zero LLM tokens. Runtime includes full CLI Q and full recorded epoch baseline/refresh H once, not their already-included scan portions. For positive g_i = D_i - (A_i + Q_i), the first strictly cheaper count is floor(H / g_i) + 1. Other gaps have no finite break-even; missing comparable components suppress only the affected total.

Command classifications are not Git processes. Named-file-size proxies are not scan bytes or filesystem I/O. No net I/O savings, task-ready latency, CPU, memory, freshness lag, historical DB size, or routine cue-runtime trends are invented. Current validation cost is visible separately. See CLI usage for import, cutoffs, and external periodic publication. Fresh real-agent calibration remains separately authorized; reporting installs no scheduler and launches no model.

Independent task comparison

evaluate-task compares an existing overview with original task context using task-specific benchmark, answer, runner, and evaluation contracts. Preparation invokes no agent by default. Explicit runner mode performs one ordered pair. A separate summary launches no process.

Actual CLI process costs include complete stdout, duration, bytes, estimate, exit, and digest. Refresh maintenance is separate; initial baseline cost remains unavailable in this path. Adapter wall time is not task-ready latency. CPU, memory, filesystem I/O, and account billing remain not_observed.

Attempts are recorded before launch outside the evaluated checkout. Raw provider/runner streams and pre/post content evidence survive failures, invalid output, cancellation, and source mutation. Incomplete journals remain visible. No retry or continuation is automatic.

Discovery scoring compares actual selector-derived required IDs and sources. Verification needs every frozen command’s identified completion, expected exit, and complete matching output. Explanation needs independent cited-source assessment. Provision, execution, correctness, and compliance remain distinct.

Credit uses complete compatible usage and dated per-million-token credit rates. Cached input and reasoning output are subsets; cue tokens are already input. Missing cost data cannot be zero-filled or replaced by partial totals. Wrong answers remain in cost inventory.

credits = ((input - cached_input) * input_rate
         + cached_input * cached_input_rate
         + output * output_rate) / 1000000

Cached input is included in input; reasoning is included in output and has no additional term. Supply dated credit rates applicable to the exact account, model and standard/fast setting. Codex credit billing has no separate cache-write charge; API-key usage follows separate API pricing [2]. The estimate is not an account-billing observation.

RepoCue controls submitted CLI stdin, model/reasoning/speed arguments and the captured final-answer schema. The CLI controls hidden context and provider calls. The task-first prompt retains the full cue. This path provides no cache TTL/breakpoint control, complete provider-wire capture or output-token cap; an ordered pair of CLI executions does not cap HTTP requests or charges. Observed cached input cannot identify which supplied source was cached. Reducing the cue may reduce both input and cached tokens; compare complete paired credits with quality instead of optimizing cache hit ratio alone.

Without --runner, actual preparation retains both cue inputs and their timings, pins, policy, schema and repository content basis. Record the actual RepoCue executable’s path and digest alongside the prepared evidence; preparation does not automatically retain executable identity. Submitted stdin is captured only at an explicit attempt. This is input preflight evidence, not a model run, correctness assessment or savings result.

Summary validates frozen and captured evidence, then calculates matched overview-minus-task differences before medians/ranges. Required pair coverage, successful tasks, and complete delivery gate the verdict. Three repeats are descriptive. Local fixture results do not establish real savings.

The task benchmark reference defines the three examples, fixed nine-pair schedule, independent assessment bindings, provider evidence limitations, and paid preflight. Canonical M5 / G3 retains model, policy, rates, spending, evidence, and pilot-continuation decisions.

Independent provider prompt-cache comparison

evaluate-cache uses separate cache-benchmark/request/observation/answer/ evaluation versions. Preparation freezes deterministic original context and exact wire bytes. Each explicit run sends one bounded non-streaming Claude request and retains failure evidence. Summary is read-only and recomputes raw usage and quality; legacy calibration and Codex credit contracts are unchanged.

Compare complete compatible baseline/cache cycles including initial writes and outputs. Usage categories are disjoint and nullable; optional supplied decimal USD rates are dated and model/API specific. Known unsuccessful cost is retained, and unknown attempts suppress complete totals. Cache intentions do not establish hits. Savings verdicts require observed reuse and complete successful quality with bound independent compliance assessments. See Prompt Cache Evaluation for source boundaries, local fixture limits, contracts, and explicit commands.

References

[1] OpenAI. “Non-interactive mode.” ChatGPT Learn. Accessed: Oct. 9, 2026. [Online]. Available: https://learn.chatgpt.com/docs/non-interactive-mode

[2] OpenAI. “Pricing.” ChatGPT Learn. Accessed: Oct. 9, 2026. [Online]. Available: https://learn.chatgpt.com/docs/pricing

Task context contracts

Scope

A task cue delivers author-declared original repository context for an explicit task and target set. This reference defines applicability, source identity, budgeting, and evidence boundaries for agents and declaration authors.

Out of scope: runtime instruction priority, permissions, global skill loading, semantic summaries, source-command execution, and paid experiments. Delivered instructions remain subject to the agent runtime’s own rules.

Versioned public values

All schemas are embedded locally under docs/schema/. Unknown fields, duplicate JSON members, trailing values, and invalid UTF-8 fail strict parsing. Runtime validation also checks IDs, paths, ranges, tracked membership, and digest relationships that JSON Schema cannot establish. Existing overview and calibration contracts retain their versions. Task results cannot enter the direct/basic calibration importer.

Declaration and applicability rules

The example declaration pins the repository README. Its digest must be renewed explicitly after the README changes. The declaration itself must be tracked and match its snapshot digest.

The dimensions combine with AND; each list combines with OR. Multiple targets select the union. cmd matches cmd/main.go, but not cmdline/main.go. An existing target directory also covers descendant item scopes. A lexical target for a future file is valid. Explicit . covers the repository.

Paths are canonical relative slash paths with exact case. Empty, absolute, drive-qualified, backslash, control-character, traversal, and noncanonical paths fail. Missing task/target and unknown task names fail. Targets are sorted and deduplicated; items are ordered by ID.

RepoCue preserves conflicting instructions as distinct items. It does not resolve authority or infer applicability from prose. Coverage is the declared set, not every instruction a runtime can load.

Original source identity

Each reference contains path, full-file SHA-256 content_digest, and lines. Null selects the whole file. Otherwise start and end are inclusive, positive, one-based line numbers with end >= start.

A selected line includes its original LF delimiter. CRLF bytes remain CRLF. An unterminated final line stays unterminated. Empty whole files are valid; ranges beyond actual lines fail. Invalid UTF-8 anywhere in the full file fails, including bytes outside a selected range.

Expected, snapshot, and actual full-file digests must agree. Extracted text also has text_digest. Source IDs hash path, full-file digest, and range. Identical references share one source record; every item retains its primary and check-source IDs.

Declaration, source, and intermediate-component symlinks fail. Gitlinks, untracked files, deleted entries, and nonregular files fail. Reads use a contained root, metadata checks, and streamed full-file hashing. Refresh never silently renews pins or reinterprets ranges.

The repository must remain idle during scans. Pre/post extraction checks do not provide a race-free repository-wide snapshot. See the scan assumption.

Whole-unit budget and failure rules

The CLI requires --view task, --context-file, --task-kind, and repeatable --target. See the CLI reference.

refresh-needed prevents delivery; matching dirty-but-indexed is valid. The complete envelope includes provenance, required IDs, original primary/check sources, and optional omission accounting.

Required units precede optional units. Optional units are admitted whole in item-ID order. Omitted items retain ID, reason budget, and count. All selected source/check references are validated even when optional text cannot fit. No text or provenance is truncated.

The estimate is ceil(serialized UTF-8 bytes / 4), not a model tokenizer. Mandatory overflow, unavailable sources, stale pins, invalid references, and declaration errors return nonzero with no successful task cue stdout. Retained text is bounded by the output budget; full-file hashing streams.

Delivery and task outcome evidence

JSON escaping does not change decoded text. Command names, invocation, and final assertions cannot prove reads/checks. Missing completion, output, or provider support stays unavailable. Provision does not establish understanding.

Assessments bind task/policy identity, attempt, answer digest, repository fingerprint, assessor, rubric, and original references. Missing policy or semantic evidence suppresses the corresponding outcome. Fixture assessments verify software handling only.

Retained local measurement boundary

Preparation refreshes an existing cache and measures actual overview/task CLI stdout and full process duration. Initial baseline cost is unavailable here. Default preparation invokes no agent.

Explicit runner mode performs one ordered pair outside the checkout. An immutable attempt-start journal precedes launch. Raw prompt, cue, settings, provider/runner output/error, and pre/post repository evidence survive failures and cancellation. Failed second arms retain completed first arms. No automatic retry or continuation occurs. The pair freezes the answer-schema digest before launch. Each adapter verifies and captures those bytes, then supplies the attempt-local schema to the provider.

Summary launches no process. It validates retained input, digests, transport, and repository compatibility, including frozen and delivered answer-schema identity, then recomputes outcomes. Wrong and incomplete answers remain in inventory. Local digests establish consistency, not provider signatures.

Complete compatible usage and dated credit rates permit an estimate. Cached input and reasoning output are subsets. Cue content is already input. Missing full-run data never becomes a partial subtotal or zero.

Matched overview-minus-task differences precede medians and ranges. A verdict requires frozen policy, successful required tasks, complete required delivery, compatible complete pairs, and the exact required pair count. Three repeats provide descriptive results, not significance. CPU, memory, filesystem I/O, task-ready latency, and billing have no measurement path here. See the task benchmark for paid preflight.

Explicit prompt-cache evaluation

Scope

evaluate-cache prepares original task context, sends individually selected Claude Messages requests, and summarizes retained observations. It is for discovery and explanation tasks with a tracked task-context declaration.

Out of scope: tools, streaming, command execution, automatic retries, background requests, Codex credits, account billing, and automatic paid runs. The task contract defines source pins and selection.

Data flow

Preparation invokes the actual refresh and task-cue CLI against an initialized cache. It validates original sources and repository basis, then freezes the benchmark, cue, answer schema, and exact requests in a unique external directory. Preparation requires no API key and sends no provider request.

Each request contains fixed system instructions and two user text blocks. The first holds declaration identity, sorted selected items, and original sources once. Explicit cache steps put cache_control with the frozen TTL on this block. Baseline steps omit it. The second holds task and current Git/freshness/ budget metadata. Source bytes are unchanged. Full wire bytes must fit the benchmark’s estimated context budget; required content is never truncated.

Reusable identity includes the model, API version, TTL, system instructions, output schema, fixed thinking/effort settings when present, output bound, and first block. Changing only task/Git metadata preserves that identity. Changing selected content or settings changes it. This local identity does not prove provider eligibility or a cache hit.

Run reserves one attempt directory before checking current source bytes and basis. It reads ANTHROPIC_API_KEY only after local preflight, then sends one non-streaming HTTPS POST. It records request-write evidence, bounded raw response, nullable HTTP details, wall time, and post-request basis. Failed or interrupted attempts remain visible and cannot be retried in that directory.

Observation started_at and finished_at contain the whole attempt, including Git/source preflight and postflight. Separate nullable http_started_at and http_finished_at retain the actual adapter interval; duration_ms derives from those times. A failure before HTTP leaves all three HTTP values null. Summary validates attempted state, containment, and duration consistency. For TTL evidence, use the HTTP request start associated with observed cache write/read usage as the latest observed access, rather than the journal start or response end. This does not automate waiting or establish provider expiry.

Summary reads frozen files only. It reconstructs requests, validates digests, and recalculates usage, answer quality, and costs without Git, subprocesses, network, credentials, or evidence writes. Digests establish local consistency; they are not provider signatures or proof against coordinated evidence edits.

Commands

Start from an initialized idle checkout with a tracked declaration. Adapt the benchmark example to its real paths and selection. The example has no rates and does not establish current pricing.

benchmark=/absolute/path/to/cache-benchmark.json
evidence=/absolute/path/outside/the/evaluated/checkout
repocue evaluate-cache prepare --benchmark-file "$benchmark" --output-directory "$evidence"

Preparation accepts --repository, --cache-dir, and --cue-binary. The default cue executable is the current binary. Output identifies the unique prepared directory. An uninitialized cache fails instead of initializing it.

Only an explicit run contacts the provider. Set the API key in the caller’s environment; keep it out of shell history and benchmark files. Run steps in their frozen order, selecting exactly one per invocation:

prepared=/absolute/path/to/the/prepared/cache-eval-directory
repocue evaluate-cache run --input-directory "$prepared" --step baseline-a
repocue evaluate-cache run --input-directory "$prepared" --step baseline-b
repocue evaluate-cache run --input-directory "$prepared" --step cache-a
repocue evaluate-cache run --input-directory "$prepared" --step cache-b
repocue evaluate-cache summary --input-directory "$prepared"

The default endpoint is https://api.anthropic.com/v1/messages. --endpoint permits an explicit HTTPS loopback TLS fixture. Other endpoints, non-HTTPS URLs, credentials in URLs, queries, fragments, and redirects fail. No application retry, follow-up request, or automatic expiry wait exists. Changed-prefix experiments use separately prepared changed source content; expiry probes require the operator to wait outside RepoCue. Conditions are intentions and never override observed usage.

Contracts and limits

All fields are explicit. Unknown fields or versions, duplicate JSON members, trailing JSON, invalid paths, inconsistent usage, or incompatible rates fail. Provider responses permit extension fields while duplicate members and unsafe counters still fail. The answer example is illustrative schema data, not a captured provider answer.

The supported local model profiles are claude-sonnet-5-5, claude-sonnet-4-6, claude-opus-4-6, claude-opus-4-7, claude-sonnet-4-5-20250929, claude-opus-4-5-20251101, and claude-haiku-4-5-20251001. They use API version 2023-06-01 and explicit 5m or 1h TTL. This list is a bounded adapter profile, not a live availability guarantee. Provider-specific minimum cache sizes and model output limits still apply.

Sonnet 5.5 freezes thinking.type=between_tools and output_config.effort=high alongside output_config.format. Without tools, this thinking setting returns text [1]. Neither setting is a public benchmark control. Older profiles omit both fields, preserving their request bytes and reusable identities. An unexpected thinking block fails the text-only answer contract; complete compatible usage and its cost remain visible independently. Local TLS verification does not establish provider availability or cache reuse.

These bounds are not spending guarantees. A credential-echoing response body is withheld. External artifacts contain repository source text and raw answers; they are distinct from content-free SQLite snapshots.

Accounting and quality

Ordinary input, cache writes, cache reads, and output are disjoint. The cache write aggregate validates the lifetime parts but is not added again. Both lifetime parts must be consistent; absent parts are allocated only when the single explicit TTL makes the allocation unambiguous. Missing counters are unknown, including when other categories are observed zero. Optional thinking usage is a subset of output and is not charged twice.

Rates are optional decimal strings in usd_per_million_tokens, with an explicit record ID, nonfuture date, exact model/API version, ordinary input, 5m write, 1h write, read, and output prices. Supply rates appropriate to the actual provider pricing conditions. RepoCue applies no universal cache discount and does not fetch prices. Estimates are not invoices. A response-model mismatch or incomplete required usage suppresses cost. Known cost of an unsuccessful task remains in inventory; unknown attempts suppress the complete total.

A pair matches ordered baseline/cache prompts under frozen settings and basis. Differences include the entire cycle, initial creation, and output. Probes are separate. A savings verdict additionally needs positive observed cache-read usage, successful source delivery, correctness, and independently assessed compliance for every paired answer. Lower cost alone is insufficient.

Each matched pair also separates initial_request_usd (the first cache-arm request, including any observed creation), subsequent_requests_usd (all later cache-arm requests), and observed_reuse_count (requests with positive cache read). These values do not assume the initial request was cold. An unknown read counter makes the reuse count unavailable; no subsequent requests makes their total unavailable. Full-cycle cost never omits the first request.

Discovery checks the exact selected required item/source sets. Claims must cite valid delivered sources. Explanation correctness and instruction compliance need external independent assessment. summary --assessment-file accepts a cache-evaluation-1 assessment bundle bound to each step’s benchmark, request, raw response, normalized answer, source IDs, basis, assessor, and rubric. An assessment cannot override failed deterministic checks or rejected bindings.

HTTP wall time is observed separately from preparation process costs. Account billing, CPU, memory, filesystem I/O, task-ready latency, and time to first token remain not_observed. Local synthetic TLS fixtures verify these software rules; real cache activity and savings require actual authorized provider runs.

Codex CLI companion measurement

Use the existing evaluate-task overview/task comparison for Codex CLI. It records total input, cached input, output, optional reasoning output, dated credit estimates, cue/adapter duration, supported command events, source delivery, and independently assessed task correctness. See Evaluation and the task benchmark reference. Codex credits have no separate cache-write charge; API-key usage has its own pricing [2]. Claude USD estimates and Codex credits remain separate populations.

Prepare the tracked explanation benchmark without selecting or running a model:

task=docs/benchmarks/task-context-v1/explanation.json
evidence=/absolute/path/outside/the/evaluated/checkout
repocue evaluate-task --task-file "$task" --output-directory "$evidence"

Use an already initialized maintained cache. Without --runner, preparation freezes actual refresh/overview/task outputs, timings, source pins, policy, answer schema and repository basis in a unique child. Record the actual RepoCue executable’s path and digest alongside that evidence; preparation does not automatically retain executable identity. It does not capture submitted stdin until an explicit runner attempt.

RepoCue supplies CLI stdin, model/reasoning/speed arguments and the final-answer schema. The CLI controls its hidden context and provider calls. The existing task-first prompt includes the complete cue; this path adds no explicit cache boundary, TTL control, full provider-wire capture or output-token cap. Two CLI executions do not bound HTTP request count or charges. Cached-input counters do not identify which original source was reused. A smaller cue can reduce both input and cached tokens; compare complete paired credits and quality instead of maximizing cache hit ratio.

Paid execution requires separately frozen model/settings, CLI version, applicable dated credit rates, independent assessment policy and spending conditions. Start with one authorized explanation A/B pair, then stop for the continuation decision. The full schedule remains nine pairs and eighteen executions including the pilot. No-model preparation establishes input readiness only; it establishes no provider behavior, correctness or savings.

References

[1] Anthropic. “Claude Sonnet 5.5 migration guide.” Claude Platform Docs. Accessed: Oct. 9, 2026. [Online]. Available: https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide

[2] OpenAI. “Pricing.” ChatGPT Learn. Accessed: Oct. 9, 2026. [Online]. Available: https://learn.chatgpt.com/docs/pricing

Task context benchmark reference

Scope

Version 1 compares the existing overview with original task context. This reference defines task inputs, scoring, fixture limits, and paid preflight.

Out of scope: direct/basic calibration, global skills, automatic model selection, automatic retries, and continued-conversation inference.

Original task specifications

The examples use the tracked declaration.

These are local preparation examples. They do not authorize paid execution. Exact paid sources, thresholds, rubrics, and assessors must be accepted before model outcomes exist.

Paired inputs and retained outputs

A is the frozen overview; B is repocue/task-cue-1. Both receive the same task, declaration path, targets, checks, model, reasoning, speed, read-only setting, and answer schema. Both can inspect original sources. Actual cue sizes can differ; the common estimate budget stays fixed.

Each invocation prepares both actual CLI paths and optionally runs one pair. Unique task-pair-* directories retain benchmark.json, answer schema, optional rates, maintenance/cue costs, manifest.json, and attempt directories.

The pair records output_schema_digest from the actual answer.schema.json bytes before attempts. Each runner request binds that digest and pair schema path. The adapter checks the bytes, retains an attempt-local answer.schema.json, and supplies that captured file to the provider’s --output-schema argument.

Attempts retain attempt-start.json, attempt.json, cue, prompt, request, submitted prompt, captured answer schema, invocation, provider JSONL/stderr, and runner stdout/stderr. Incomplete journals remain visible. Raw partial usage never becomes a full total.

Summary resolves its input directory to the absolute physical directory. It validates frozen inputs, digests, captured transport, and the answer schema’s pair/request/capture/invocation identities before recalculating metrics and outcomes. Missing or changed schema evidence keeps attempts visible and prevents a complete comparison. Optional assessment bundles have repocue/task-evaluation-1 and kind assessments. Assessments bind task, policy, attempt, answer, fingerprint, assessor, rubric, and original references.

Credit and quality calculation

Rates require ID, nonfuture as_of, model, speed_tier, unit credits_per_million_tokens, and input/cached-input/output rates. The formula is ((input-cached)*input_rate + cached*cached_rate + output*output_rate)/1000000.

Input includes context. Cached input and reasoning output are subsets. Missing reasoning alone preserves otherwise complete credit inputs. Missing counters, incomplete turns, incompatible rates, subset violations, and overflow make the estimate unavailable.

Wrong and incomplete attempts remain visible. Pair differences are overview minus task; medians and ranges summarize matched differences. Known/unknown coverage belongs to each metric. Credit estimates are not account billing. A verdict needs successful required tasks, complete required delivery, and the frozen policy’s exact pair count.

Fixed paid comparison schedule

The two-execution pilot is the first explanation pair. Continuation requires explicit approval. Nine pairs contain 18 executions including the pilot. Order imbalance stays visible: 2:1 per task and 5:4 overall. Three repeats support descriptive values only.

Paid experiment preflight conditions

Before G3 authorizes the pilot, freeze:

• Reviewed revision, HEAD/fingerprints, declaration, source/check pins, task files, answer schema, and common cue budget.
• Provider executable/version, model, reasoning, speed, sandbox, and observed support for required usage/completion/output fields.
• Digest-bound success/rubric, independent assessor, exact pair/evidence coverage, and treatment of missing semantic evidence.
• Dated applicable credit rates and external evidence location.
• Authorized execution count, spending stop controls, and pilot continuation.

One pair bounds execution count, not charges. The adapter has no hard billing ceiling. Unsupported evidence can prevent a complete conclusion. Local software approval does not resolve G3.

Local verification boundary

Tests build the shipped CLI and runner, use real Git/SQLite, and substitute only external Codex. Verification fixtures execute the declared Go test. Failed arms, malformed output, cancellation, mutations, missing evidence, wrong commands, partial output, and cheaper wrong answers use the real path.

Synthetic usage, completion flags, rates, and assessment judgments verify software handling. They establish no actual provider support, charge, agent compliance, savings, or continued-conversation benefit.

RepoCue Current Status

Updated: 2026-10-08 UTC

Accepted Foundation

RepoCue has an accepted Go vertical slice, Core Evaluation and Hardening, and real Codex A/B validation. The maintained basic cue reduced observed tokens, commands, explicitly named files, and elapsed time in the initial three- repository experiment. The earlier derived byte proxy increased, and semantic completeness remained unresolved.

The default distribution is CGo-free. Linux static and Windows amd64 cross-builds are required. SQLite remains the canonical local store.

Scan Operating Assumption

Repository files and Git state must remain unchanged during an individual scan. Each scan captures one Git basis; changes between scans are still detected. SQLite transactional publication and checks before and after external agent runs remain in place. See Architecture.

A status, refresh, or overview cue at an ordinary repository root invokes Git three times when its validated location cache is available. A cache miss adds one discovery call. Subdirectory requests, linked worktrees, special Git configuration, submodules, and newline-containing paths retain the required additional queries. Core scan behavior and the persisted index digest format are unchanged. Branch identity retains Git’s short symbolic-ref format, including disambiguated names when branches and tags share a name.

Next Milestone

M3 local M1 and M3 are Complete in milestone-10a4f02.md, with independent implementation and closure acceptance. Reporting landed in a8f650c; the token correction landed in 8d61f6e, which matches origin/master and GitHub master as observed on 2026-09-08 UTC. The implementation adds calibration import, stdout-only JSON/Markdown reports, content-sensitive evidence, and schema-3 references. Reports separate recorded maintenance from paired future-consumer estimates and never launch an agent.

Real Git/SQLite/CLI fixture tests cover incompatible input, correctness, optional assessments, untracked-content changes, publication rollback, history, and cue process measurement. These use a synthetic runner, not observed real-agent savings. T1-T22 passed; the canonical test matrix records the executed checks and their limits. Initial real-agent calibration remains blocked on G1; no new model runs are authorized.

The draft measurement plan compares three direct/basic pairs on RepoCue itself using Codex 0.153.4, gpt-5.6-luna, medium reasoning, benchmark/answer version 2, read-only execution, and a 500-token basic overview budget. The exact clean commit and execution cost require approval. G1 records current rate references, an explicitly assumed cost illustration, and a first-pair cost checkpoint; actual token use, duration, and savings remain unmeasured.

The separately authorized local M3 correction preserves missing/null token counters as not_observed and explicit zero as observed. New evaluations use report/runner version 4; imports also validate unchanged version-3 reports under their original contracts. Complete input/output values still produce a total when cached or reasoning usage is absent.

The actual adapter/evaluator/import/report fixture path passed five presence cases with matching JSON/Markdown measurements and preserved Git-fact scores. A report set produced by the pre-change CLI was imported unchanged; producer incompatibility still correctly prevents using it for projections. Full tests, race, vet, tidy, static Linux and Windows builds, and mdBook passed; independent correction and final second-person review were accepted with no remaining finding. These verification results remain dated 2026-09-08 UTC; the status update does not represent a new product test run.

No real model run is authorized. Writable local cache access remains a measurement preflight requirement; the earlier read-only sandbox observation has not been resolved. M2 remains Blocked on G1 approval; see the canonical M2 preflight and G1 for the remaining measurement conditions and cost checkpoint.

Task context implementation

Task context implementation provides separate version-1 contracts, pinned original-source delivery, whole-unit budgeting, and an opt-in one-pair local evaluation path. Built CLI/runner tests with real Git/SQLite and only external Codex substituted cover successful checks, retained failures, cancellation, source mutation, missing evidence, and cheaper wrong responses. Frozen and provider-supplied answer-schema bytes are digest-bound. Summary rejects changed schema/request evidence and resolves relative and symlink directory aliases.

M4 remains In progress until required distribution/documentation/independent acceptance checks and Git landing are recorded in the canonical milestone. M5 remains Blocked on M4 and G3. No paid task experiment, real provider evidence capability, account billing, or task-context savings has been measured. The task benchmark reference lists the exact paid preflight and proposed pilot/continuation schedule.

Deferred Scope

• MCP
• production Tree-sitter or other parser backend
• persistent structural index
• embeddings or LLM use inside RepoCue
• checkpoint management
• pruning and retention enforcement
• filesystem watching

RepoCue Work Register

Scope

This document is the canonical work register for quantitative reporting, repository calibration, task-specific context delivery and measurement, and provider prompt-caching integration.

Out of scope: Implementation or external agent execution before their separate authorization, and every feature listed in the M1 and M2 exclusions.

Release line: master Milestone index: 10a4f02 Canonical path: docs/milestone-10a4f02.md Canonical branch or ref: master Git upstream: origin/master Remote tracker: none

Next session entry point: use the local extension execution handoff under work/review_sessions/20261009_072038_prompt-caching/handoff/ to bind exact paid conditions to the final no-model inputs. Sonnet P008-P009 (plan20261009_092451) and Codex CLI P010-P011 (plan20261009_160442) are implemented under auth20261010_025018; both independent implementation reviews accepted the target with zero findings/blockers, and local source, race and distribution checks passed. G6’s two-request Sonnet pilot and USD 0.10 allowance remain proposed and do not apply to Codex; G3 still needs exact Codex model/settings, applicable dated credit rates, assessment and spending conditions. No real-provider request or savings observation exists. M5/G3 and M6/G6 remain separately Blocked/Open; new commit/push needs separate authority. Prior P001-P006 landed in d6f94b7. M2/G1 is unchanged.

Milestone

Work

Decisions

Milestone Details

M1 - Quantitative Savings Report Contracts And Implementation

Origin: 10a4f02 / M1 Identity History: none GitHub Issue: none Status: Complete

Summary

Add a model-neutral reporting path that combines observed RepoCue maintenance measurements with a separately produced A/B calibration. The report answers what changed in RepoCue’s own cost and what savings are projected for repeated consumers without presenting projections as observed use.

The canonical machine-readable output is versioned JSON. Markdown is generated from the same calculation result. Every metric carries its measurement status, basis, unit, sample count where applicable, and limitations.

Scope

• Add a repocue/calibration-1 JSON contract for compact aggregates imported from complete, validated evaluation report sets.
• Add a repocue/savings-report-1 JSON contract for observed local metrics, calibration provenance, applicability, like-for-like trends, and reuse projections.
• Add a repocue/calibration-evidence-1 JSON contract for report digests, pairing, producer provenance, repository profiles, full-path cue costs, deterministic scoring evidence, and optional assessment references. Preserve existing evaluation-3 and qualitative-assessment-2 files.
• Add repocue calibration import --reports <directory>.
• Require --evidence <file> for import and accept optional --assessments <directory>.
• Add repocue report, --window <Nd>, --format json|markdown, --profile <calibration-id>, and --consumers <positive-integer> options. JSON is the default format.
• Store calibration JSON under the RepoCue cache directory and store only its reference and SHA-256 digest in SQLite.
• Compare the selected time window with the immediately preceding equal window for like-for-like observed maintenance and cue metrics.
• Prepare direct/basic evaluation pairs through an explicit evaluate-m2 --conditions direct,basic option. Preserve the existing default five-condition behavior and its atomic publication and isolation checks.
• Measure the shipped basic cue CLI before each assisted run and supply its output to that agent. Retain the complete command duration and observed Git invocation count in external calibration evidence, not new history tables.
• Import and report branch, HEAD, dirty, tracked-change, and untracked-path correctness independently of optional semantic assessments.
• Add content-sensitive evidence capture for evaluation, calibration import, and reporting without indexing untracked content in the core snapshot.
• Interpret legacy measurement coverage explicitly and define historical state selection by observation time using existing stored timestamps.
• Include external cron and systemd examples that write report stdout to an operator-selected destination.

Out of scope: MCP, Claude adapter, production source parsing, Tree-sitter, embeddings, RepoCue-internal LLM use, checkpoint management, pruning, retention enforcement, filesystem watching, an internal scheduler, automatic report retention, and a single cross-unit total-cost score.

Completion Criteria

• A complete compatible direct/basic report set imports deterministically into a schema-valid calibration artifact with an independently verifiable digest.
• Cross-repository, incomplete, incorrectly paired conditions, mixed-model, mixed-benchmark, mixed-budget, or otherwise incompatible selected input is rejected without publishing a calibration reference.
• The default report shows fixed 1, 2, 3, 5, and 10 consumer projections and no headline claiming observed savings.
• --consumers N is labeled as an explicit scenario and never inferred from cue runs.
• Token projections use agent-observed direct and assisted totals without adding cue estimated tokens a second time. Token components remain separate.
• Wall-duration projections are labeled as execution-duration projections. Task-ready latency remains not_observed.
• Per-consumer cue duration and Git cost cover the real CLI, including its freshness inspection. Builder-only or missing measurements never stand in for this cost; affected combined projections remain unavailable.
• Observed scan bytes and agent named-file-size proxies remain separate. No I/O savings value is emitted from unlike measurements.
• CPU, memory, filesystem bytes read and written, freshness lag, and any other unavailable required metric are present as not_observed, not omitted or reported as zero.
• Report windows are segmented by epoch. No projection crosses an epoch boundary or uses a not_applicable calibration.
• Exact-basis, compatible-snapshot, and incompatible calibration states are distinguishable from the report alone. Compatible estimates show tracked file, byte, and language-profile changes from the measured reference.
• Qualitative results are carried only as dated calibration evidence and are never described as an assessment of the current snapshot.
• Deterministic Git-fact results retain each response’s pass count, fact count, ratio, and per-fact pass/fail values with provenance and paired coverage. Incorrect answers remain in both quality and efficiency results; missing scoring evidence is explicit and never means a passing score.
• JSON and Markdown contain the same values, measurement classifications, limitations, and provenance.
• A break-even consumer count is reported only for a comparable dimension with a positive per-consumer difference. Zero, unfavorable, or unavailable cases explain why no break-even value exists.
• Reports contain no raw agent response, prompt, or absolute evaluated- repository path.
• The default CGo-free Linux static build and Windows amd64 cross-build remain available.
• Import matches the complete live repository fingerprint to source evidence and the maintained snapshot before atomically binding the profile to the local epoch. An identically numbered snapshot in another DB is insufficient.
• Legacy reports without verifiable producer provenance are rejected with the missing fields identified; current executable metadata never fills them in.
• Activity-window boundaries, profile selection, pairwise aggregation, and maintenance-cost boundaries follow the contracts below.
• Untracked content changes at an unchanged path invalidate exact evidence matching even when the core snapshot ID and Git status remain unchanged.
• Legacy placeholder zeros never become observed savings. A historical report separates state observation time from metric recording time and makes no claim about SQLite publication time.
• Optional assessments have an unambiguous validated join, explicit coverage, and recorded assessment time when available. Absent scores or dates are not inferred.

Repository Binding And Evidence Contract

Import requires an initialized repository and a maintained tracked snapshot that matches the live repository. Evaluation, import, and report share a versioned evidence capture covering branch, HEAD, index/status, tracked working tree, and non-ignored untracked paths and content. The source repository ID and this content-sensitive fingerprint must match the target checkout; neither HEAD nor the existing names-only untracked fingerprint is sufficient. M3 does not automatically transfer calibration between different checkout roots.

For non-ignored untracked regular files, hash content as a stream. Include the repository-relative path, kind, mode, and content digest in a deterministically ordered, unambiguously encoded inventory. Hash symlink target text without following the target. An unreadable or unsupported entry prevents a complete evidence result; never silently omit it or follow a link outside the checkout. The evidence scope is Git state plus tracked and non-ignored untracked entries, not every file on disk. Preserve the existing submodule limitations explicitly. Apply the idle-repository scan assumption and retain pre/post agent checks.

Store only evidence digests, algorithm/version, coverage, and observation metadata in calibration/binding data; file contents and detailed inventories remain external. Keep evaluation-3’s original fingerprint as provenance and carry the stronger fingerprint separately in calibration-evidence-1. Compare only fingerprints produced under the same algorithm. Do not reinterpret or overwrite old report or assessment fingerprints. Legacy evidence without contemporaneous proof of the stronger coverage cannot establish a binding.

This capture belongs to evaluation, import, and report, not ordinary core refresh or cue generation. It adds no untracked file-state rows or parser. Record its duration and bytes read in external evaluation evidence separately from cue CLI cost and agent cost; routine report output identifies its own current validation work without claiming it is free or adding history tables.

The importer records the source snapshot IDs only as provenance. After evidence validation, it binds the profile to the target repository ID, active epoch, local snapshot, and verified fingerprint. The SQLite transaction compares the expected current epoch and snapshot again before publishing the reference; a concurrent refresh or rebaseline aborts the import. This prevents a temporary evaluation DB’s snapshot-000001 from being mistaken for the local DB’s state.

For a current report, compare the live tracked basis with the maintained snapshot and the additional content-sensitive evidence with the calibration binding. A tracked mismatch reports refresh-needed and suppresses projections; the command does not refresh automatically. Changed untracked content under the same core snapshot makes the calibration not_applicable and suppresses projections without falsely changing core freshness. Repeating ordinary refresh alone cannot repair that evidence mismatch; renewed authorized calibration evidence is required. For an unchanged binding and matching content-sensitive fingerprint, applicability is measured_reference. A new snapshot in the bound epoch with the same producer/cue contract is estimated and displays the repository-profile changes. A new epoch or incompatible contract is not_applicable; source measurements remain visible as historical reference values. Model and reasoning settings belong to the selected profile, not to an inferred active agent session.

repocue/calibration-evidence-1 names report files relative to --reports and records each SHA-256 digest, pair ID, condition, run index, and source snapshot. Its file references reject absolute paths, parent traversal, and symlinks that resolve outside the declared input directories. Each pair has exactly one direct and one basic report with matching repository basis, maintenance ID, runner settings, benchmark, and answer schema. Across pairs, maintenance IDs may differ, but repository basis and execution contracts must agree. Reject duplicate pairs and duplicate source-report digests.

The evidence file also records the RepoCue source revision and executable digest, fingerprint algorithm version, cue view/schema/budget and selection policy version, repository language profile, and the observation times. The extended evaluation path emits these values when it prepares the reports; import never derives historical values from the currently installed executable or a later checkout. Add schema/runtime validation and file-digest checks for this evidence contract in internal/evaluation and the calibration importer.

The direct/basic preparation path records full CLI cue-cost observations and the contemporaneous Git basis used for deterministic scoring in the external evidence file, joined to each selected report by digest, pair ID, condition, run index, and state fingerprint. Nested external evidence references follow the same relative-path and digest validation rules as report references.

Existing evaluation-3 reports can be used only when retained contemporaneous records substantiate the missing fields. The evidence file names those records and their digests. Reject unsupported legacy input without modifying its files or fabricating a version, language profile, or fingerprint. Old five-condition sets may supply explicitly selected direct/basic reports through the evidence file; other conditions are excluded, not aggregated. Inconsistent selected conditions remain an error. Runnerless dry-run reports cannot calibrate agent savings.

A single complete pair may be imported with sample_grade: exploratory; projections display that grade. Initial M2 completion requires at least three complete pairs, six agent runs. Three runs provide descriptive ranges, not a statistical significance claim.

Calculation And Measurement Contract

All arithmetic operates on complete matched pairs for each measurement. If one side is unavailable, exclude that pair for that measurement, record the reason and coverage count, and use not_observed when no complete pairs remain. Sample ranges are minimum and maximum, not confidence intervals. Median uses the arithmetic mean of the two middle values for an even sample count.

For a measurement dimension and pair i, define:

D_i = observed or derived direct-agent cost
A_i = observed or derived basic-assisted agent cost
Q_i = separately measured full basic cue CLI cost, when comparable
H   = local epoch maintenance cost through the report cutoff
g_i = D_i - (A_i + Q_i)

direct_i(N)   = N * D_i
assisted_i(N) = H + N * (A_i + Q_i)
saving_i(N)   = direct_i(N) - assisted_i(N)

Calculate these values per pair before reporting medians and ranges. The headline saving is median(saving_i(N)), not a subtraction of independently aggregated arm medians. Display pair values and sample counts so the result can be reproduced; independently reported medians need not add up. Percentage savings are calculated per pair relative to its positive direct total before aggregation. A zero direct total has an unavailable percentage.

For example, direct costs [100, 200, 300] and paired assisted costs [90, 1, 299], with Q and H equal to zero, have differences [10, 199, 1]. The median difference is 10; subtracting arm medians would incorrectly give 110 for this specified statistic. Retained pairs preserve the association needed to reproduce the result. Calibration statistics are derived; future consumer scenarios are estimated, including at an exact measured basis.

For tokens, assisted input already includes the cue. Q is zero additional agent tokens, justified by that accounting boundary, and estimated cue tokens are diagnostic only. Input, cached-input, output, reasoning-output, and total tokens remain separate; cached input is a subset of input, and reasoning output is not added again to a total that already includes it. In this deterministic no-LLM core, H has zero LLM tokens by construction, explicitly labeled derived, while maintenance runtime and scan costs remain reported. Do not convert tokens into currency without a separate pricing basis.

For execution duration, Q is the externally measured wall duration of one successful shipped repocue cue --view overview invocation in the same evaluation pair, from process launch through exit after stdout is fully captured. It includes startup, repository/location-cache and SQLite access, freshness inspection, serialization, cue-metric recording, and output. Supply those captured bytes to the assisted agent; do not measure one invocation and deliver a separately generated cue. Record executable digest, arguments, cache/location-hint state, observation times, exit status, and output digest in the external evidence. Require the expected snapshot, basis, schema, budget, and current or dirty-but-indexed freshness before launching the agent. Existing pre/post repository-state checks remain in force.

The in-process builder duration in existing evaluation-3 reports excludes these CLI operations. Keep that value as a separately labeled diagnostic; never substitute it for Q or add it again to a full CLI duration. When full-path evidence is absent, Q is not_observed and combined duration projections and their break-even values are unavailable. Agent-only duration comparisons remain visible with that narrower boundary. This measurement belongs to calibration evidence; routine reporting does not execute cue or collect a new runtime-duration history.

H is the recorded local epoch baseline (or the rebaseline that created that epoch) plus refresh durations from committed rows whose recording times are before the cutoff. This is an accounting boundary, not proof of publication before that instant. Use the full recorded operation duration, not operation duration plus its already included scan duration. Its unrecorded failed-operation and maintenance-process-startup costs remain outside H and are disclosed. Do not charge a cue’s freshness scan again as refresh maintenance: it is already inside Q. The result is a serial execution-duration projection of the stated components, not elapsed time for concurrent consumers or a complete system-cost measurement. Task-ready latency remains not_observed.

For command counts, distinguish agent-command projections from total Git invocations. Agent-command comparisons exclude RepoCue internal operations and identify that boundary. Total Git projections use recorded maintenance Git invocations as H and observed Git invocations from the full cue CLI as Q, charged once per consumer. Capture these invocations at the real process boundary; do not substitute the builder’s zero Git calls or a hard-coded count. If observation is unavailable, Q is not_observed, not zero. Keep evaluation setup and pre/post agent isolation checks outside Q and identify them as experiment overhead. Do not combine generic tool calls, Git subprocesses, and agent commands into one count. An unavailable component suppresses only the affected total.

Do not charge calibration experiment baselines or agent runs as repeated production maintenance. Display calibration execution costs separately. Live H always covers the bound epoch from its creation, including a baseline that predates --window; the window controls the observed activity/trend section only. Record operation IDs and cutoff used for H. Missing epoch baseline evidence at the cutoff makes combined runtime/Git projections unavailable, even when the baseline’s state observation precedes the cutoff. Do not combine this epoch’s H with a profile from another epoch.

For each pair with g_i > 0 and H >= 0, the first strictly cheaper positive consumer count is floor(H / g_i) + 1. Thus equality at N is not break-even under this definition, and zero maintenance with a favorable difference starts at one consumer. For g_i <= 0, record no_finite_break_even; for missing costs, record not_observed. Show per-pair results and finite-result coverage; show a finite range only across finite results, without hiding non-finite pairs. Never issue a cross-unit break-even result.

Historical operation duration, files/bytes scanned, Git commands, cue bytes, estimated cue tokens, and counts use existing operation/cue rows. Compare per-operation medians and counts as well as totals so more activity does not automatically appear to be a performance regression. An unavailable prior period has no percentage trend; a complete period with no recorded events has zero recorded activity. Show observation coverage and do not assume cache history existed before its creation.

Schema version 2 alone does not prove historical measurement coverage. The version-1 migration assigned DEFAULT 0 to scan_duration_ms and git_commands, so a zero in either field without independent evidence that it was measured is not_observed. Do not infer a measurement boundary from the current executable, a guessed date, or the first nonzero row. Preserve raw stored values; annotate their interpretation in report output. This rule is specific to these ambiguous fields, not valid recorded zeros such as bytes scanned by a no-op refresh or separately observed zero-cost measurements.

Expose known and unknown row counts per dimension. Known-only aggregates may be shown with explicit partial coverage but cannot stand in for a full total, percentage trend, H, or break-even result. Suppress only the totals affected by unknown components; a missing Git count does not erase recorded duration. No destructive history rewrite or new measurement-history table is required.

Current database size is a point measurement with its observation time. Historical database-size trends and runtime cue-generation duration trends are not_observed because the current schema does not retain them. Full cue CLI duration from calibration remains a separate measured reference with its recorded environment and cache state, not a live measurement for later snapshots. M3 adds no history collection for these values. CPU, memory, filesystem read/write bytes, freshness lag, and task-ready latency likewise remain not_observed when their observation path does not exist. Scan bytes and named-file-size proxies are separate metrics and never produce a net I/O-savings calculation.

CLI And Periodic Execution Contract

The working implementation provides these commands; use a real imported profile ID.

repocue calibration import --reports /tmp/repocue-pairs --evidence /tmp/calibration-evidence.json --repository .
repocue report --repository .
repocue report --repository . --window 30d --format markdown
repocue report --repository . --profile calibration-example --consumers 5

Both commands accept --repository PATH (default current directory) and the existing --cache-dir PATH override. Import prints the created calibration ID, artifact path, digest, sample grade, and target binding as JSON. An unchanged import is idempotent; it returns the same ID. Changing assessment content or source evidence creates a distinct immutable profile. Derive the ID from normalized evidence digests and the local binding; exclude import wall-clock time from that identity. A later epoch needs a new verified binding and ID.

report defaults to JSON and 30 days. --window Nd accepts a positive integer number of fixed 24-hour days, with checked arithmetic. Capture a single UTC cutoff t at command start; use [t - N days, t) and the immediately preceding equal interval. Add optional --as-of <RFC3339-UTC> for repeatable reports over recorded observations, rejecting future cutoffs. Select the retained snapshot with the latest observed_at strictly before the cutoff; break timestamp ties by snapshot sequence. This means the state observed before the cutoff, not a snapshot proven published before it. Use parsed UTC instants rather than lexical comparisons of variable-width RFC3339 timestamps.

Use [start, cutoff) for activity rows and strictly-before-cutoff selection for bindings. No eligible snapshot yields unavailable historical state, not the current snapshot as a substitute. If the chosen state precedes the cutoff but its baseline metric does not, show the observed state and unavailable H. Do not reconstruct publication time from duration or add publication history.

Current live checks and current database size are separate observations, never historical facts. Historical applicability uses only retained binding/state evidence available for the selected observation basis; absent evidence suppresses projections, and today’s fingerprint never fills a historical gap. A later live change alone does not rewrite a historical observation. Profile selection for a historical cutoff considers only bindings observed before it; an explicitly selected later binding remains visible but cannot project. Emit the cutoff, time meanings, profile digest, observation times, and stable ordering; comparisons normalize report-generation time and explicitly current live observations. Newly retained observations can change a repeated historical report; reproducibility requires the same DB/evidence read basis as well as the same cutoff, not an assumed historical copy of the database.

With no --profile, zero profiles produces maintenance data with unavailable agent projections; one profile selects it and reports its applicability; multiple profiles produces maintenance data and a profile-selection-required warning listing IDs and model/benchmark labels, with no agent projection. An explicit unknown profile ID, bad digest, invalid argument, or unreadable DB is an error. A valid but inapplicable profile remains visible with projections suppressed. Deleting the cache also removes its calibration copies; restore by reimporting retained evidence, with the binding rules applied again.

The default consumer scenarios remain 1, 2, 3, 5, and 10. --consumers N adds one explicitly requested positive-integer scenario, without duplicating an existing value. Periods spanning epochs show activity per epoch and never sum consumer projections across them. A selected profile can project only its bound epoch, which must be active at the cutoff.

report does not refresh, record a cue run, persist a generated report, or silently migrate an old database. It reads a coherent DB transaction and checks live evidence without modifying source files. Schema version 2 is supported read-only: report its available maintenance history with no calibration profiles, so reporting works before the first import. Other unsupported schemas fail explicitly. Concurrent changes yield one coherent result or a defined retryable error. Follow existing CLI exit conventions: success and informational unavailable results use exit 0; failures use exit 1 with the existing JSON error format on stderr.

Scheduling documentation must specify absolute executable, repository, cache, and output paths. Schedule report only; refresh remains an explicit operator action. Show freshness and observation cutoff in every report. The caller publishes stdout through a temporary file and rename only after exit 0 so an error cannot replace a previous good report. Document external overlap prevention for one destination. No daemon, timer installation, or automatic artifact retention is performed by RepoCue.

Deterministic Git-Fact Correctness Contract

Validate and score each selected final response through the shipped internal/benchmark.ParseAndScore path against its contemporaneous Git basis, not a later repository state. Evidence must bind that basis to the report’s state fingerprint and digest and record the benchmark/answer schema, scorer revision, and scoring time. Recompute rather than trust supplied score totals. Keep the source basis and raw responses in external evidence; do not copy the scorer’s expected/actual values into calibration JSON, SQLite, or reports.

For each response, preserve report digest, pair ID, condition, run index, scoring provenance, pass count, total fact count, ratio, and named per-fact pass/fail results for branch, HEAD, dirty state, tracked changes, and untracked paths. Calculated correctness is derived from the observed answer and verified basis. A schema-valid wrong answer remains a scored failure, not an import rejection or an excluded efficiency sample. Invalid answer shape or contradictory supplied evidence remains an import error.

Display direct and basic ratios with medians, ranges, scored-response counts, per-fact pass counts, and paired correctness differences calculated before aggregation. Only complete scored pairs contribute to paired comparisons; retain other valid individual scores and expose their coverage. Legacy input that satisfies the repository-binding contract but lacks verifiable scoring basis has not_observed correctness and a named limitation, not an inferred pass. Show failed facts or incomplete correctness coverage alongside any efficiency projection; do not claim equivalent quality from numeric savings.

These results concern Git facts at the measured basis only. They neither establish semantic completeness nor become renewed quality measurements when a profile is used for a later snapshot. Optional qualitative assessments remain separate and their absence never suppresses available Git-fact scores.

Qualitative Assessment Contract

--assessments <directory> is optional. When supplied, the evidence file maps each relative assessment path and SHA-256 digest to one selected report digest and response ID. Validate the existing qualitative-assessment-2 schema and match condition, run index, repository HEAD, and state fingerprint to that report. Reject missing mapped files, ambiguous or duplicate response mappings, mismatched basis, and mixed assessors within an aggregate. Require one selected assessment per response; never average conflicting assessor judgments silently.

The importer preserves the six numeric scores, assessor, response ID, rubric version, report/assessment digests, and coverage. Assessment time comes from contemporaneous provenance in the evidence file because assessment-2 has no timestamp field. If unavailable, report it as not_observed; import time and file modification time are not assessment time. Measurement time and source repository basis remain visible even when assessment time is unknown.

Aggregate each dimension only across complete assessed pairs, with median, range, and assessed-pair count. No assessments yields not_observed semantic quality and quality-not-assessed; partial coverage is explicit. This does not replace the separate deterministic Git-fact results. Numeric efficiency projections can still be shown, but they do not establish maintained context quality. Do not modify scores or persist free-text assessment evidence, agent responses, or prompts in calibration JSON or SQLite. Keep those externally under their digests for independent inspection. Runtime Git freshness is a separate current observation, not a renewed semantic assessment.

Dependencies And Decisions

• D1-D23 define the accepted reporting and storage boundaries.
• M1 has no dependency on G1; implementation and local fixture verification can finish before real calibration evidence is authorized.
• The report must follow the evaluation requirements in docs/PROJECT_BRIEF.md and the evidence boundary in docs/DATA_MODEL.md.

Implementation Plan

Plan Status: accepted Plan Acceptance: 2026-09-07 Implementation Authorization: User authorized the current M1 implementation on 2026-09-07; no real-agent calibration or Git publication. Superseded Plan Artifacts: none

1. Add an ADR defining the calibration artifact boundary, SQLite reference boundary, applicability states, per-dimension accounting, and absence of an aggregate cross-unit cost score. Include content-sensitive evidence scope, ambiguous legacy zero handling, and observation-based historical reporting.
2. Add JSON Schemas for repocue/calibration-1, repocue/calibration-evidence-1, and repocue/savings-report-1, including explicit measurement status, unit, basis, limitations, source-file joins, full CLI cue-cost observations, deterministic Git-fact results, and nullable values for not_observed measurements. Extend the evaluation preparation path to emit evidence and allow direct/basic-only execution. Measure the shipped cue executable and deliver its captured stdout; preserve default five-condition behavior and old report schemas. Verify through T13 and T18. Add the shared content-sensitive capture at evaluation, import, and report boundaries, including pre/post agent checks; retain legacy fingerprints as separate provenance. Verify same-path content changes through T20.
3. Add a calibration importer that validates every source report and its shared repository, state, runner, model, reasoning, benchmark, output-schema, cue-schema, cue-view, cue-budget, RepoCue-version, selection-policy, tracked file count, indexed byte count, and language-profile metadata before calculating paired medians, ranges, and sample counts. Implement the exact source-to-local binding, deterministic scoring through the existing benchmark package, and optional assessment joins defined above. Reject legacy evidence that cannot supply verified required provenance; retain missing optional observations explicitly. Verify correctness and privacy through T9 and T19.
4. Write calibration JSON atomically below the repository’s RepoCue cache directory. Publish its SQLite reference only after validating the final file digest; reject missing or changed referenced artifacts when reporting.
5. Migrate SQLite from schema version 2 to version 3 with only calibration reference and applicability metadata. Preserve transactional rollback and do not store raw reports or agent responses.
6. Implement one calculation model shared by JSON and Markdown. Keep token, command, execution-duration, scan, storage, and proxy-byte dimensions separate; never add unlike units into one total.
7. Implement exact-basis, compatible-snapshot, and incompatible applicability. A change in epoch, repository identity, RepoCue contract, cue contract, agent/model configuration, benchmark, or output schema makes the profile inapplicable. A compatible snapshot remains an estimate and reports its tracked-file, indexed-byte, and language-profile drift without inventing an unsupported validity threshold. Distinguish core freshness from a changed untracked-content binding under the same snapshot; suppress that profile’s projections without promising that ordinary refresh repairs it. Verify T20.
8. Implement epoch-segmented time windows and equal-window trends for the existing baseline, rebaseline, refresh, files-scanned, bytes-scanned, Git-command, cue-count, cue-byte, and cue-token-estimate history. Report current database size separately and mark unavailable historical size and runtime cue-duration trends not_observed. Interpret ambiguous legacy zeros per dimension without rewriting stored rows or inventing measured values; verify coverage and suppressed totals through T21. Use the explicit time mappings for state, activity, H, and binding selection; verify T22.
9. Implement fixed reuse projections and explicit consumer scenarios. Show baseline and refresh as one-time maintenance, assisted agent totals as per-consumer cost plus full cue CLI cost where comparable, and negative results without suppression. Show deterministic correctness alongside the costs. Calculate break-even separately for each comparable dimension and handle zero, unfavorable, or unobserved per-consumer differences without division. Verify full-path accounting and missing costs through T15 and T18.
10. Emit required but unavailable CPU, memory, filesystem-I/O, freshness-lag, and task-ready-latency measurements as not_observed with the missing observation named. Keep named-file-size proxies as a separately labeled diagnostic value.
11. Add CLI and operator documentation, including calibration provenance, stale-evidence warnings, stdout-only report handling, and external scheduling examples using the CLI contract above. Update docs/ARCHITECTURE.md, docs/DATA_MODEL.md, docs/EVALUATION.md, and docs/CLI.md only when the described behavior is implemented. Run a mandatory second-person documentation pass before commit.

Test Plan

Verification Results

Verification commands use GOCACHE=/tmp/repocue-m3-go-cache on this host:

go test -count=1 ./...
go test -race -count=1 ./...
go vet ./...
go mod tidy -diff
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /tmp/repocue-m3-linux ./cmd/repocue
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o /tmp/repocue-m3-windows.exe ./cmd/repocue
make docs.build
git diff --check
gofmt -l cmd internal docs/schema

Named CLI tests are in internal/app/reporting_test.go; storage tests are in internal/storage/reporting_test.go; calculation/history tests are in internal/reporting/; cue process tests are in internal/evaluation/calibration_test.go; content tests are in internal/repository/evidence_test.go. The external agent is synthetic. These results verify software behavior, not actual agent savings. Full Windows runtime execution, hardware power loss, and installation of cron/systemd schedules were not performed. Builds preserve go.mod and go.sum unchanged.

Independent storage/evidence/history and evaluation/calculation/CLI reviews accepted the working implementation on 2026-09-07, including the required second-person documentation checks. Independent closure acceptance followed on 2026-09-08 UTC. The accepted implementation is committed and matches the fetched upstream. No new real-agent calibration was performed; M1 acceptance establishes the reporting path, not real Codex measurement coverage or savings.

Closure Evidence

• Complete: 2026-09-08 UTC. Implementation and required T1-T22 checks are recorded above; no linked GitHub issue or unresolved M1 external gate exists.
• Commit: a8f650cc8950015b22a7873001ef72234ea3cf3c, Add evidence-based savings reports; 34 implementation, contract, and documentation files. The separately authorized commit and push completed.
• Landing observation: 2026-09-08 00:31:16 UTC, origin/master fetched; local HEAD and upstream both resolve to that commit. The working tree was clean and the full tracked-file comparison against origin/master had no differences. Recheck with git fetch origin, git status --short --branch, git rev-parse HEAD origin/master, and git diff --exit-code origin/master.
• The closure cross-check accepted the 34-file candidate and its status derivatives. The later schema-only EOF correction was verified with the shipped schema tests and diff check before publication; it did not change schema values. The broader verification above remains dated 2026-09-07.
• This closes the implementation work unit, not the local review-session directory. Session removal and new Git publication are not authorized.

GitHub Projection

Title: Add quantitative savings reports Labels: none GitHub Milestone: none Observed State: none Observed Labels: none Observed Milestone: none Last Compared: never

M2 - Initial Repository Calibration And Report

Origin: 10a4f02 / M2 Identity History: none GitHub Issue: none Status: Blocked

Summary

Produce the first repository-specific calibration and periodic report only after the reporting path is complete and the User authorizes the evidence source. A single direct/basic pair verifies the pipeline but remains exploratory. Reported ranges require at least three controlled pairs per arm. The initial target is the RepoCue repository itself at the exact basis recorded in G1. Results are repository-specific and do not establish general cross-repository effectiveness.

Scope

• Validate an authorized retained report set or run fresh direct/basic pairs.
• Use the same repository state, Codex version, model, reasoning, benchmark, output schema, sandbox, cue view, and cue budget for every pair.
• Produce at least three complete pairs for the initial calibration.
• Generate and independently re-derive the first report and its fixed reuse projections.

Out of scope: additional experimental conditions, optimization based on the result, or selection of a structural backend.

Completion Criteria

• At least three valid direct/basic pairs exist for one exact repository basis.
• Before and after content-sensitive fingerprints show matching Git, tracked, and non-ignored untracked state for every agent run, including untracked content. They do not claim coverage of ignored files or intermediate writes.
• The calibration records median, range, sample count, exact run metadata, and source-report-set digest.
• The source set includes calibration-evidence-1 with verified producer provenance, paired report digests, full cue CLI duration and Git observations, deterministic Git-fact results with scoring basis, and any optional assessment joins. Retained sets missing these observations do not complete M2; renewing evidence remains subject to G1 authorization.
• The first report distinguishes observed local maintenance, measured reference values, compatible estimates, unavailable metrics, and explicit consumer projections.
• An independent calculation reproduces every projected token, command, and execution-duration value.
• Independent scoring reproduces the five Git-fact outcomes for every response, including failures; quality and efficiency results use the same selected responses with explicit coverage.
• No significance claim is made from three runs.

Dependencies And Decisions

• M1 and the M3 token correction are Complete in a8f650c and 8d61f6e.
• G1 must be Complete; resume as Not started after all dependencies complete.
• If retained source reports cannot be verified, G1 requires a separate cost estimate and User authorization for new Codex runs.

Implementation Plan

Plan Status: draft Plan Acceptance: none Implementation Authorization: none Superseded Plan Artifacts: none

1. Resolve G1 with the exact report source, repository basis, run count, model, reasoning, sandbox, benchmark, cue budget, and estimated run cost.
2. Validate retained reports or run the authorized direct/basic pairs without modifying the evaluated repository. Use the explicit two-condition path and retain its evidence JSON, full CLI cue costs, and contemporaneous scoring basis with content-sensitive pre/post evidence; six agent runs form three complete pairs. Do not replace missing historical observations with current CLI timings, untracked content, or Git state.
3. Import the complete report set with its evidence file, bind it to the same repository’s current local epoch, and record the calibration artifact digest. Include authorized assessments when available; otherwise report semantic quality as not_observed.
4. Generate JSON and Markdown reports for 1, 2, 3, 5, and 10 consumers.
5. Recompute all derived values independently from the retained reports and evidence, including full-path cue accounting and deterministic correctness, and compare them with the generated report.
6. Record findings without claiming general significance or actual unobserved consumer savings.

Measurement Preflight

Observed on 2026-09-08 UTC at implementation commit a8f650c:

• The repository contains 101 tracked files and 837,608 Git blob bytes, derived from git ls-tree -rl HEAD. This is a corpus profile, not measured scan I/O.
• The local CLI reports codex-cli 0.153.4; codex login status reports ChatGPT authentication. No model availability probe or agent run occurred.
• No retained real direct/basic report set was found in the repository or its local work/ artifacts. Synthetic integration fixtures are not calibration.
• The Codex adapter at a8f650c loses missing usage fields. An isolated Go test overlay reused TestRunInvokesCodexAtOutermostBoundary, omitting only reasoning_output_tokens from the external Codex fixture’s usage event and adding a missing-value assertion. The unmodified shipped Run path emitted reasoning_output_tokens: 0 with status observed; the assertion failed. The input, cached input, and output values remained 10, 0, and 5. Only the external executable boundary was substituted; production code was unchanged. Evidence locations: internal/codexadapter/adapter_test.go and internal/codexadapter/adapter.go (codexUsage, buildObservation).
• The adapter observation conflicts with D2. Its separately authorized correction and missing-versus-zero verification belong to M3 below. This is not a claim that Codex 0.153.4 always omits that field.
• Routine local refresh encountered a read-only cache database in the current sandbox. Cache write access must be established before local calibration binding; no cache initialization or permission change was performed.

These preparation checks do not complete M2 / T1-T4. The owner authorized the bounded M3 token correction separately; G1 still excludes new Codex runs.

The correction subsequently landed in 8d61f6e on 2026-09-08 UTC; M3’s completion evidence is recorded below. That resolves the token-correction prerequisite, not G1 authorization or the writable-cache preflight.

Test Plan

Verification Results

Closure Evidence

• none

GitHub Projection

Title: Calibrate RepoCue and publish the first savings report Labels: none GitHub Milestone: none Observed State: none Observed Labels: none Observed Milestone: none Last Compared: never

M3 - Token Usage Absence And Report Compatibility

Origin: 10a4f02 / M3 Identity History: none GitHub Issue: none Status: Complete

Summary

Preserve missing Codex token observations without erasing available costs or correctness. Introduce evaluation and runner version 4 while retaining strict read compatibility for unchanged version-3 reports.

Scope

Optional per-turn counters, complete-turn aggregation per counter, checked arithmetic, adapter provenance, matching version dispatch, local regression tests, and current contract/status documentation.

Out of scope: real model runs, calibration acceptance, SQLite changes, new dependencies, performance optimization, and changes to existing v3 schemas or retained report bytes.

Completion Criteria

• Missing/null counters stay unavailable and explicit zero stays observed.
• A completed turn without usage is retained; partial coverage never yields a complete aggregate. Input/output alone determine total tokens.
• Invalid counters, overflow, unknown/mixed versions, and malformed legacy input fail explicitly. Unrelated measurements and correctness survive.
• The real adapter/evaluator/import/report path and actual pre-change v3 report bytes pass the checks below, with independent review.
• Required checks and the reviewed correction have Git landing evidence.

Dependencies And Decisions

M1 supplies the reporting path. D2, D14, and D24 define measurement presence and version compatibility. G1 is not needed for local fixture verification; it remains required for real calibration. The separately authorized commit and push completed on 2026-09-08 UTC.

Implementation Plan

Plan Status: accepted Plan Acceptance: 2026-09-08; bounded independent evaluation preflight accepted Implementation Authorization: 2026-09-08; User authorized missing-token correction, new JSON versions, and existing-report read compatibility Superseded Plan Artifacts: none

1. Retain actual pre-change v3 output before editing the implementation.
2. Update internal/codexadapter/adapter.go, internal/evaluation/m2.go, and internal/evaluation/usage.go for optional counters, complete-turn aggregation, checked arithmetic, and v4 execution.
3. Add docs/schema/evaluation-v4.schema.json and docs/schema/evaluation-runner-v4.schema.json; dispatch imports in internal/evaluation/calibration.go and internal/reporting/calibration.go without weakening v3.
4. Exercise the shipped paths in adapter, evaluation, schema, and CLI tests. Keep the actual legacy output under internal/evaluation/testdata/.
5. Update docs/EVALUATION.md, this detail, and docs/CURRENT_STATUS.md; independently verify the bounded correction before Git publication.

Test Plan

Verification Results

The golden v3 report was generated through the real prepareReportingFixture path at a8f650c, not by relabeling current output. Its SHA-256 is 681b676c0a0d12cb14237ed530fd9ccf32bc9353867affd7f0a973fe78b1c463. The new CLI imported the unchanged original direct/basic set and retained its declared zeros. Producer incompatibility correctly suppressed projections for that old executable; read compatibility does not waive applicability. No actual agent token savings or Codex 0.153.4 usage coverage was measured.

Closure Evidence

• Complete: 2026-09-08 UTC. Required T1-T4 results and independent correction, second-person, and closure acceptance are recorded; Git publication is complete. M1 remains Complete.
• Commit: 8d61f6e65ab01ebbaef90ea2e6352b87235e195d, Preserve missing token measurements across evaluation reports; 17 implementation, test, contract, and documentation files. The separately authorized commit and non-forced push completed.
• Publication rechecked on 2026-09-08 UTC: local HEAD, origin/master, and GitHub refs/heads/master resolve to that commit. The working tree was clean before this status-only update. Recheck with git rev-parse HEAD origin/master, git ls-remote --exit-code origin refs/heads/master, and git status --short --branch.
• Product verification above remains dated 2026-09-08; it is not a new test run for this status update. No real calibration has occurred; M2 remains Blocked on G1. Whole-session closure, removal, and new Git publication are not authorized by this status update.

G1 - Calibration Evidence Authorization

Origin: 10a4f02 / G1 GitHub Issue: none Status: Open

Summary

The User selects and authorizes the evidence source for M2. The source may be a retained raw direct/basic report set that passes current validation or newly run Codex pairs with an explicit cost estimate and pinned execution conditions. Legacy reports without sufficient contemporaneous provenance cannot satisfy this gate solely because their original report schema validates.

Draft Execution Conditions

Prepared: 2026-09-08 UTC. These are proposed settings, not execution authority. The initial corpus is RepoCue only; no other local repository is included.

The current evaluator requires direct then basic within each pair. This draft keeps that order and reports the order/cache bias; it does not claim randomized assignment. Both arms inherit the same available instructions and environment; --ignore-rules concerns execution-policy rules, not a guarantee that repository instruction files are absent. Audit direct-arm commands for unintended RepoCue use before treating a pair as direct discovery.

Stop after the first pair to report observed usage, duration, deterministic correctness, and any failure; obtain confirmation before the remaining two pairs. A failed or interrupted pair is incomplete and does not authorize a replacement run. Stop on state drift without reset or clean. Record attempts and exclusions instead of selecting only favorable or correct responses.

Cost Preparation

No same-repository real-run evidence is available to forecast token consumption or elapsed time reliably. The 500-token cue budget limits only the cue, not the agent’s total input, output, or execution time. A numerical time estimate and a hard spending ceiling are unavailable; the current adapter has no built-in deadline or billing cap. The first-pair checkpoint bounds the number of initially started runs, not their token cost.

Rates retrieved on 2026-09-08 UTC: GPT-5.6 Luna uses 5 credits per million uncached input tokens, 0.5 per million cached input tokens, and 30 per million output tokens [1]. ChatGPT authentication does not establish the account’s remaining allowance, credit balance, or extra charge; those are not observed.

For an explicitly assumed six-run total of 1.5 million uncached input tokens and 120,000 output tokens, the base-rate illustration is 11.1 credits. It is not a measured prediction, approved budget, or maximum. Recalculate from the first pair before proposing the remaining four executions.

For comparison only, the API base rates are USD 0.20 / 0.02 / 1.20 per million input / cached input / output tokens [2]. The same assumed uncached scenario is USD 0.444 before adjustments, not an estimate of this ChatGPT account’s bill. Requests over 272,000 input tokens have 2x input and 1.5x output rates; cache writes use 1.25x uncached input rates [2]. Aggregate run usage alone cannot reconstruct these request-level charges.

Completion Criteria

• The evidence source, exact conditions, run count, repository basis, and any external execution cost are recorded with User authorization.

Verification Results

Closure Evidence

• none

M4 - Task-Specific Context Delivery And Local Measurement Readiness

Origin: 10a4f02 / M4 Identity History: none GitHub Issue: none Status: Complete

Summary

Provide a small task-specific context cue for repository instructions, design decisions, and verification procedures. Explicit task and path matching selects author-declared source references. Deterministic extraction delivers the chosen original text with its source identity, current content digest, snapshot, and freshness. The source remains authoritative; a cue does not grant permission or establish that an agent understood or followed it.

Local measurement readiness adds the evidence contract and real-path checks needed for M5. Existing command classification is insufficient to establish successful source delivery or verification execution because it does not retain command exit status or output in the runner observation.

Scope

• A versioned JSON declaration records item ID, kind, explicit task/path applicability, required status, original-source reference, and completion check reference. Sources belong to the evaluated Git repository.
• A separately versioned task cue selects applicable items and provides original-source text and provenance without automatic semantic summaries.
• Define source selection, digest checking, stable output ordering, missing inputs, conflict/ambiguity reporting, and required-versus-optional budgeting.
• Add explicit CLI task and target-path inputs, schema validation, source extraction, freshness checks, and measurements for the complete shipped cue path. Keep existing overview/delta/provenance behavior and contracts.
• Extend the external evaluation boundary to retain supported command completion/output evidence; unsupported fields remain not_observed.
• Define a separate task benchmark and answer/result contracts. Do not feed task/basic evidence into the existing direct/basic calibration importer.
• Add local real Git/SQLite/CLI fixtures, contract checks, distribution checks, and functional documentation of data flow and evidence limitations.

Out of scope: global skill rewriting, relaxing required skill reads, external home-directory indexing, executing declaration-supplied commands, runtime permission enforcement, real model execution, MCP, embeddings, source parsers, LLM summarization, SQLite source-text storage, history pruning, and automatic deployment or Git publication.

Completion Criteria

• An explicit task and target path produce only applicable context, including all applicable required items and their source identities.
• Selected source text matches the real file bytes/range and digest used to build the cue. Missing, changed, or ambiguous sources cannot produce a complete successful result.
• Required-item budget overflow fails explicitly. Optional omissions are counted and reported. Unknown matching inputs never silently exclude a potentially required item.
• Source references cannot escape the repository through absolute paths, traversal, or symlink targets.
• Delivery evidence, command success, correctness, and compliance have distinct fields and explicit availability. The implementation never equates a command name or final-response declaration with successful verification.
• Existing output/schema and real-path regressions pass without altering frozen calibration semantics or introducing a parser runtime dependency.
• T1-T8 and independent plan/implementation acceptance are recorded; Git landing evidence is required before marking the milestone Complete.

Dependencies And Decisions

D25-D30 define the accepted owner direction from the implementation and measurement plan. G2 is Complete after the User confirmed L size / Mode B on 2026-10-07. G4 owns acceptance and implementation authorization for the reviewed named M4 plan and is Complete on 2026-10-08. M2 / G1 is a different experiment and is not a behavioral dependency. M5 consumes the reviewed measurement contracts. The User requested registration and trying the preceding plan on 2026-10-07; no real-model or Git-publication conditions were selected.

Implementation Plan

Plan Status: accepted Plan Acceptance: 2026-10-08; User accepted plan20261008_052832, P001-P007, after both correction reviews. Implementation Authorization: 2026-10-08; User authorized plan20261008_052832, P001-P007; auth20261008_072718 records the exact scope and exclusions. Superseded Plan Artifacts: none

Named plan: plan20261008_052832, local review artifact work/review_sessions/20261008_050539_task-context/plan/plan20261008_052832_codex_gpt6_root.md. Review basis: HEAD 34d6d902365fb9ff4292996cafe0c18fd50c7d71 plus this session’s uncommitted milestone registration. Two initial independent reports were read; convergence conv20261008_052115 includes all four measurement-plan readiness findings. Both independent correction reviews accepted plan readiness; owner acceptance and implementation authority are recorded under G4.

Accepted contract choices: OR within explicit task/path lists, AND between dimensions, global dimensions and union across targets; canonical component-aware relative paths; whole files or inclusive 1-based line ranges; expected and snapshot full-file digests plus extracted-text digests; original UTF-8/line endings retained; declaration/source symlinks, linked intermediate components, gitlinks and untracked sources rejected. Every selected source/check failure is an error. Required sources/checks/provenance remain whole under the budget; whole optional units may be omitted with explicit IDs/count/reason. These policies describe declared coverage, not all runtime instructions.

1. P001 - Contracts and ADR. Add six new schemas under docs/schema/: task-context-v1.schema.json, task-cue-v1.schema.json, task-benchmark-v1.schema.json, task-answer-v1.schema.json, task-runner-v1.schema.json, task-evaluation-v1.schema.json. Add docs/TASK_CONTEXT.md, docs/task-context.example.json and docs/adr/0003-task-context-delivery-and-evidence.md; extend schema tests. Keep existing versions unchanged. Verify T1 and T8.
2. P002 - Selection and source. Add internal/taskcontext/{declaration,selection,source}.go and tests. Bind tracked declaration/source/check bytes to expected and snapshot digests; use contained regular-file access and deterministic range selection. Source text stays transient; SQLite remains content-free. Verify T1-T3.
3. P003 - Task cue and shipped CLI. Add internal/cue/task.go, internal/app/task_context.go, tests and shipped fixtures under internal/app/testdata/task-context/; update app flags/help/dispatch. cue --view task requires --context-file, --task-kind and repeatable --target; legacy views reject task-only flags. Task mode rejects --since, --path and refresh-needed state. Build the complete mandatory envelope before optional budgeting. Test the actual executable over real Git/SQLite. Verify T2-T4 and T6.
4. P004 - Benchmark and scorer. Add internal/taskbenchmark/, docs/benchmarks/task-context-v1.md and three original task specifications. Bind prompt/tool/source/answer/assessment identity and required-check coverage. Explanation needs a source-backed rubric/assessment; instruction ID correctness and command success remain distinct. Missing policy or semantic evidence cannot award success or improvement. Verify T5.
5. P005 - Task transport. Add internal/codexadapter/task.go and tests; cmd/repocue-codex-runner/main.go dispatches only the exact task-runner contract to the new configuration. Legacy version/validators remain intact. Capture actual stdin, raw events/stdout/stderr and available completion/ exit/output evidence on failure; decode JSON source text before comparing original bytes. Verify T5-T6.
6. P006 - Attempts, costs and summaries. Add internal/evaluation/{task,task_attempt,task_cost}.go, tests, internal/app/task_evaluation.go and executable pipeline tests. evaluate-task prepares without an agent by default; explicit runner mode performs one ordered pair, with no retry or continuation. Measure both actual cue CLI paths. Create external attempts before launch and preserve first/second-arm failure, malformed output, cancellation and post-failure basis errors. Retain wrong answers and unavailable data. Credit requires complete usage and compatible dated rates; a verdict also requires the frozen task-success/coverage policy and its evidence. Task reports cannot enter the old calibration importer. Verify T5-T6.
7. P007 - Docs, checks and handoff. Update docs/CLI.md, DATA_MODEL.md, ARCHITECTURE.md, EVALUATION.md, CURRENT_STATUS.md, SUMMARY.md and this detail. Run T1-T8 through actual packages/fixtures/binaries, obtain independent implementation acceptance, and prepare the G3 settings/evidence/policy checklist. No model execution or Git publication belongs to M4.

Test Plan

Verification Results

Post-EOF fixture verification: the actual shipped CLI/runner and real Git/SQLite fixtures passed go test ./internal/app -run '^(TestTaskCueShipped|TestTaskEvaluationShipped)' -count=1 -v with exit 0, 12 top-level tests and package time 26.692s. The retained result was rechecked at 2026-10-09 04:28:25 UTC; this is not a fresh full/race/build rerun. Each of four source fixtures lost only one extra terminal LF; all other accepted source bytes were preserved. Independent EOF checks accepted the exact correction and current derivatives: E1 cmt20261009_041019 executed all four shipped TaskCue tests, and E2 cmt20261009_041323 executed all eight shipped TaskEvaluation tests. Only the external Codex provider is substituted.

Closure Evidence

• Completed on 2026-10-09 UTC: implementation, corrected T1-T8, both independent implementation acceptances, post-EOF fixture verification and Git landing satisfy M4 completion criteria. G2 and G4 are Complete; no linked issue exists.
• Source commit: edd3dc23203f9b79c6cff9b9103a156716299549, parent 34d6d902365fb9ff4292996cafe0c18fd50c7d71. All 52 committed paths and blob hashes matched the accepted EOF inventory before publication.
• Observed at 2026-10-09 04:28:25 UTC after git fetch origin: local master, fetched origin/master and source commit above are identical, with ahead/behind counts 0/0 and a clean working tree before this record update. The actual upstream state and committed source paths were checked; a push exit alone is not used as landing evidence.
• Recheck with git fetch origin, git rev-parse HEAD origin/master and git merge-base --is-ancestor edd3dc23203f9b79c6cff9b9103a156716299549 origin/master. Later documentation commits may advance HEAD; the source commit must remain an ancestor of origin/master.
• No real paid-model run, actual provider-capability verification, account billing measurement or credit savings was observed. M5 remains Blocked by Open G3; M2 / G1 and their separate conditions are unchanged.

Plan Review Evidence

• Initial C1-C3 report rev20261008_051728: no confirmed current defect; contract choices separated from conditional implementation hazards.
• Initial C4-C6 report rev20261008_051835: four readiness gaps addressed by explicit dispatch, retained attempts, evidence/scoring and success/coverage prerequisites. Its actual legacy usage-presence pipeline and failure- publication checks passed; these do not establish M4 behavior.
• Named correction plan20261008_052832 has P001-P007 and exact V001-V010 commands mapped to T1-T8. Both independent correction checks and G4 are complete.
• C1-C3 correction report fup20261008_054213, finalized 2026-10-08 05:42:13 UTC: no remaining confirmed plan defect; matching, source/range/digest/link/budget choices and preservation checks are reviewable.
• C4-C6 correction report fup20261008_054053, finalized 2026-10-08 05:40:53 UTC: all four original readiness findings are accepted and reflected in the plan. No remaining verified plan blocker. Both reports were read by the coordinator; neither establishes product behavior or grants owner acceptance/implementation authority. Files remain local under work/review_sessions/20261008_050539_task-context/reviews/.
• Documentation preflight on 2026-10-08 05:34:26 UTC: make docs.build and git diff --check exited zero; the non-ASCII scan of this document, the named plan and convergence report found no matches. The generated book contains the M4 plan and G4 detail. These are plan/document observations, not completed M4 implementation checks; T1-T8 were Pending at that observation.

Implementation Review Evidence

• Initial I1 rev20261008_155804 accepts its source/selection/budget/preservation lane after independent second/third-person execution.
• Initial I2 rev20261008_155016 confirms F-codex_gpt6_r4-001: changing the archived answer schema leaves the original summary unchanged. Root executes the same retained real fixture and confirms the defect, plus relative-directory manifest rejection. Existing P001/P005/P006/P007 authority covers both implementation corrections; cmt20261008_160553 records the boundary.
• Correction regressions execute the shipped CLI/runner/outer-fixture/summary path. Actual frozen and provider-supplied schema bytes agree; missing/changed schema and changed request identity retain both attempts and suppress complete comparisons. A changed schema between arms preserves the completed first arm and prevents the second provider launch. Absolute, relative and symlink paths produce byte-identical summaries without launching providers.
• I1 follow-up fup20261008_170345, finalized 2026-10-08 17:03:45 UTC, accepts hand20261008_165535 with no remaining confirmed I1 defect. Fresh source/cue/public-example/frozen-schema tests, a separate real Git/SQLite source fixture, legacy contracts and actual static/cross-build inspections pass.
• I2 follow-up fup20261008_170912, finalized 2026-10-08 17:09:12 UTC, accepts the same target with no remaining confirmed I2 defect. F-codex_gpt6_r4-001 is verified implemented. The current Task suite and an independently compiled CLI/runner/shipped outer fixture execute five schema corruptions and physical-directory aliases. Raw argv/transport and artifact hash rebinding cannot override the frozen schema contract; two attempts stay visible and incomplete comparisons have no verdict.
• Root reads both actual reports and verifies all 52 hashes at 2026-10-08 17:10:29 UTC. Reports remain local under work/review_sessions/20261008_050539_task-context/reviews/. Each report distinguishes fresh lane checks from earlier full/race checks, synthetic accounting and unobserved real-model/billing outcomes.
• The approved plan and authorization are unchanged. This completes the second implementation acceptance review and the sole correction-and-rereview cycle. Only canonical observations/acceptance/next-entry-point and the session index advance after acceptance; product code, schemas and functional docs stay fixed.

M5 - Task-Context Agent Comparison

Origin: 10a4f02 / M5 Identity History: none GitHub Issue: none Status: Blocked

Summary

Compare the frozen existing overview against the new task-specific cue on the same repository state, model, tools, task, and execution settings. Measure total credit estimate, tokens, full cue and agent duration, additional discovery commands, required-context delivery, observable execution, and task correctness. Evaluate quality independently of efficiency.

Scope

• Three task types: code explanation with original-source evidence, applicable instruction/reference identification, and actual execution and reporting of a specified verification command.
• One initial two-execution pair validates collection and cost accounting. Subject to its explicit continuation checkpoint, three repeats per task and two conditions total 18 executions including that first pair.
• Freeze alternating order before the pilot (2:1 within each task, 5:4 overall across nine pairs) and retain model/CLI versions, reasoning, speed tier, tool configuration, prompts, source digests, budgets, cache counters, repository fingerprints, attempt IDs, outputs, and scoring evidence.
• Separate source delivery, successful command execution, result correctness, and semantic compliance. Raw evidence remains external.

Out of scope: changing legacy M2 / G1, calibrating task results as direct/basic, claiming long-conversation savings from fresh sessions, inferring cache misses, model substitutions, automatic retries, and real agent source modifications.

Completion Criteria

• Every attempted run and failed/incomplete pair remains visible; no favorable or correct-only sample selection is permitted.
• Per-task paired cost differences, medians, ranges, correctness, missing measurements, and order/cache observations are reported separately.
• Freeze a digest-bound task-success and required pair/evidence coverage policy before the first model run. A verdict requires successful required task outcomes, no missing required context or coverage, preserved paired correctness and a lower paired-median credit estimate. Equal incorrect answers do not satisfy success. Missing semantic assessment stays unavailable; partial comparisons cannot award the complete planned improvement verdict. Three repeats support descriptive findings, not significance.
• Tokens include supplied context once. Cached tokens are an input subset; reasoning tokens are an output subset. Credit calculation uses uncached input, cached input, output, and the dated applicable credit rate/speed tier. Missing cost inputs suppress the cost estimate.
• Local CPU, memory, filesystem I/O, task-ready latency, and account billing remain unavailable unless their actual measurement path is added and run.
• Required evidence, first-pair continuation decision, and final acceptance are recorded before closure; no long-conversation claim is made.

Dependencies And Decisions

M4 supplies the reviewed implementation and measurement contracts. G3 owns the exact real-model execution conditions and spending authorization; resume as Not started. D25-D30 apply. The existing M2 / G1 experiment remains a separate work identity with its original conditions and authorization.

Decision Date: 2026-10-09. The User requested Codex alongside Sonnet 5.5 and selected Codex CLI. Use the existing overview/task comparison and credit accounting. Do not add OpenAI API calls or import Claude cache-write accounting. CLI selection does not select a model or authorize paid execution. Existing runner usage and retained-input contracts remain unchanged.

Implementation Plan

Plan Status: draft Plan Acceptance: none Implementation Authorization: none Superseded Plan Artifacts: none

1. Freeze the reviewed M4 artifact basis, task files, result schemas, applicable instructions, model/settings, output directory, and credit rate record.
2. Preflight both real cue paths and evidence capture without a model. Record full CLI output and timings, digests, source availability, and correctness checks; freeze the common cue budget before model results exist.
3. Execute only the first authorized A/B pair. Report usage, cost estimate, correctness, completeness, duration, and limitations. Wait for the explicit continuation decision before the remaining executions.
4. Run authorized remaining pairs with balanced order, original-source scoring, repository-state checks, and attempt/error retention.
5. Publish a separate versioned JSON result and human-readable comparison. Record observations and acceptance here. Do not import these conditions into the existing production direct/basic calibration.
6. After first-stage evidence, prepare a separately authorized continued- conversation experiment if required. A multi-turn runner and fixed turn sequence need their own plan; fresh-session results cannot substitute.

Accepted Codex CLI Companion

Plan Status: accepted Plan Acceptance: 2026-10-09; plan20261009_160442 accepted through current User continuation Implementation Authorization: 2026-10-09; auth20261010_025018; P010-P011 only Superseded Plan Artifacts: none

Named additive proposal: plan20261009_160442 under work/review_sessions/20261009_072038_prompt-caching/plan/. P010 documents the existing CLI measurement alongside Claude API evaluation in docs/PROMPT_CACHING.md and docs/EVALUATION.md. P011 runs actual no-model preparation for the first explanation A/B pair and records M5 / T1 evidence. It preserves the original six-step M5 plan, balanced nine-pair schedule, source pins, task-first prompt, runner and public schemas. Decision Date: 2026-10-09. The User accepted and authorized both local items after review. P010 documentation and P011 no-model preparation are implemented. Initial preparation passed at the basis recorded in M5 / T1. Independent implementation reviews rev20261010_031022 (C1) and rev20261010_030956 (C2) accepted the unchanged six-file target, including C2’s second-person operational-document pass; conv20261010_031713 records zero findings/blockers and review 1 per lane. Final-state preparation follows this tracked record update; its actual child, pins, executable identity and result belong in the execution handoff under the same session. An initial preparation is not valid for a later changed basis. No model run is claimed.

The measurements are total input, cached-input subset, output, optional reasoning-output subset, complete dated credit estimate, cue/adapter duration, supported commands, delivery and independent correctness. Cache counters alone do not identify cached source text or establish causal cache savings. CPU, memory, I/O, task-ready time and account billing remain unavailable. Codex CLI executions can contain multiple provider requests. No TTL, explicit cache boundary, output-token cap or hard billing ceiling is added. G3 still requires exact model/settings, applicable account rates, assessment and spending authority. Sonnet’s proposed USD allowance does not apply.

Proposal review observed at 2026-10-09 16:21:55 UTC: C1 rsp20261009_161608 and C2 rsp20261009_161706 each completed their first review of this companion with zero findings and zero blockers. conv20261009_162155 records the result. Plan acceptance/local authority remain pending; M5 T1-T4 are still Not run. Actual proposal-document build and diff checks passed at 16:07:46 UTC. No model, successful preflight, cache saving or account charge was observed.

Test Plan

Verification Results

Closure Evidence

• none; no real model execution or savings measurement has occurred.

G2 - Independent Review Session Configuration

Origin: 10a4f02 / G2 GitHub Issue: none Status: Complete

Summary

Confirm the review-session size, execution topology, roles, and commit cadence required before M4 changes durable schema and evidence contracts. The User confirmed L size, Mode B, two independent-context Reviewers and the current agent coordinating and implementing on 2026-10-07. The initial M-size/Mode-A proposal was corrected before session creation. Publication is deferred to a separately authorized single closure; no commit or push is delegated.

Completion Criteria

• User confirmation and required role/session entry are recorded.

Verification Results

Closure Evidence

• User configuration confirmation and role recording in local session work/review_sessions/20261008_050539_task-context/README.md; product plan acceptance and implementation authorization remain separate.

G3 - Task-Context Experiment Conditions And Cost Authorization

Origin: 10a4f02 / G3 GitHub Issue: none Status: Open

Summary

Authorize the exact M5 experiment basis, model and reasoning/speed settings, dated credit rates, evidence directory, first-pair execution count, spending stop conditions, and continuation checkpoint. Authorization to develop or run local tests is not authority for real paid model executions.

Completion Criteria

• Reviewed M4 evidence and exact M5 conditions are available.
• Freeze task/answer/check identities, source-backed explanation rubric and assessor provenance, success thresholds and required pair/evidence coverage before outcomes. Missing policy or semantic evidence cannot award a verdict.
• The maximum planned credit budget and enforceable stop controls are distinguished from estimates. If the adapter cannot enforce a hard billing ceiling, state that limitation instead of presenting a two-run checkpoint as a spending cap.
• User authorizes the first pair under these conditions. Further executions need the pilot continuation decision; failure does not authorize retries.

Verification Results

Closure Evidence

• none

G4 - Named Task-Context Plan Acceptance And Implementation Authorization

Origin: 10a4f02 / G4 GitHub Issue: none Status: Complete

Summary

The User accepted and authorized reviewed M4 plan plan20261008_052832, P001-P007, on 2026-10-08. Responsible party: User. Affected work: M4. The prior request authorizes registration and preparation; final schema/measurement choices remain explicit. Both independent correction checks are complete. Owner acceptance and implementation authorization are recorded separately in M4.

Completion Criteria

• The User accepts the current named plan, including its matching, source/ range/digest/link policies and guarded evidence/comparison boundary.
• The User authorizes implementation of this exact P001-P007 plan; record acceptance and implementation authority separately in M4.
• Material changes require a superseding plan and new acceptance/authority. Paid M5/G3 and Git publication remain separate.

Verification Results

Closure Evidence

• User acceptance and implementation authorization on 2026-10-08, recorded in work/review_sessions/20261008_050539_task-context/plan/auth20261008_072718_codex_gpt6_root.md; both independent correction reports were read before authorization.

M6 - Claude API Prompt-Caching Integration And Measurement

Origin: 10a4f02 / M6 Identity History: none GitHub Issue: none Status: Blocked

Summary

Add optional Claude API prompt-caching support around RepoCue context delivery. The provider maintains the actual model-side cache. RepoCue prepares reusable context, sends cache controls through an explicit adapter, and measures the observed usage, request duration, estimated API cost and task quality. The User accepted the reviewed local plan and separately authorized P001-P006 implementation on 2026-10-09. Paid execution remains separately gated by G6.

Scope

• Separate a deterministic reusable context prefix from changing task input, repository-state metadata and timestamps. Preserve required original sources, applicability, freshness and digest checks; a real source change must change the corresponding reusable content.
• Add an opt-in Claude API adapter that controls the actual submitted request and places cache_control at the intended reusable boundary. The provider requires a matching prefix and applies model/platform-specific minimum lengths and cache lifetimes [3]; cue output alone does not establish a cache hit.
• Retain exact submitted content, selected model/API settings, prefix identity, raw response usage, request timings, failures and missing measurements.
• Measure ordinary input, cache creation by applicable lifetime, cache reads and output separately. Define provider-specific accounting before mapping to shared reports; existing Codex input-subset semantics remain unchanged.
• Compare an uncached baseline, initial cache creation and subsequent reuse under matched task/context/settings. Include changed-prefix and expiry conditions, and classify each attempt from observed provider counters.

Out of scope: implementing the provider’s model-side cache locally, controlling existing Codex or Claude Code sessions, requiring a provider for ordinary CLI use, replacing original context with LLM summaries, changing M2/G1 or M5/G3, automatic paid retries, and claiming Codex-credit or account-billing savings from Claude API estimates.

Completion Criteria

• The real adapter submits the intended reusable prefix and changing suffix; unchanged content is byte-stable and source changes preserve correctness.
• Raw usage retains the provider’s distinct ordinary-input, cache-write, cache-read and output counters. Full-input totals count each category once; missing or incompatible counters suppress dependent estimates. Claude usage semantics are checked against the applicable official contract [3].
• Cost estimates use the selected model’s dated rates, including cache-write lifetime differences, cache reads and outputs. Report initial creation cost, repeated-use totals and observed reuse count separately; no universal price multiplier or assumed hit is accepted.
• Authorized real-provider evidence establishes cache creation and reuse, plus changed-prefix and expiry behavior, from actual usage and timing observations. Retain every attempted request and task result. Local transport fixtures establish software handling only, not real cache behavior or savings.
• Paired comparisons retain source delivery and task correctness alongside efficiency. Missing quality evidence prevents an overall improvement claim; request duration is not labeled task-ready latency or account billing.
• Versioned compatibility, optional network use, Go implementation, CGo-free Linux static builds and Windows cross-builds are preserved.

Dependencies And Decisions

M4 supplies original-source task context and retained evidence boundaries. G5 owns acceptance and implementation authority for the new integration plan; G6 independently owns paid Claude API conditions and cost authority. G5 is Complete; G6 is Open. Local implementation is authorized and locally verified; resume as In progress after all external gates complete. D26-D30 apply. Registration alone does not select a model, API version, TTL, schema, run count or budget. The User selected Sonnet 5.5 on 2026-10-09 and subsequently accepted and authorized P008-P009 local support through auth20261010_025018. Paid conditions below still require their separate acceptance and authority. The User selected M6 plan preparation as the current priority on 2026-10-09. Implementation and experiment order relative to M2 or M5 remains unassigned.

Implementation Plan

Plan Status: accepted Plan Acceptance: 2026-10-09; reviewed M6 local plan, serialized by plan20261009_075715 Implementation Authorization: 2026-10-09; explicit User implementation request, approval and continuation, recorded by auth20261009_075715; local P001-P006 only Superseded Plan Artifacts: none

Accepted revision: 2026-10-09, plan20261009_075715. The User accepted this reviewed architecture and authorized local P001-P006 implementation after requesting implementation. auth20261009_075715 records that direction. Independent detailed-contract cross-checks rsp20261009_080519 and rsp20261009_080505 found zero confirmed blockers. The exact local field, CLI and HTTP-limit details are in the named plan. G6 remains separate.

Premise And Boundary

The accepted local slice is text context delivery and structured answers for source identification or source-backed explanation. It does not build a coding-agent runtime: repository writes, shell execution, client/server tools, streaming, background warming and autonomous conversations are excluded. Verification-command tasks remain unsupported in this slice and must not receive fabricated completion evidence. G5 accepted these boundaries on 2026-10-09; the existing M5 task types and runner remain unchanged.

Contracts And Data Flow

Use Go standard-library HTTP behind an opt-in evaluation command. Keep the core cue generator and SQLite content-free; do not add a provider SDK or parser runtime dependency. Public contracts are independent of task-runner-1, task-evaluation-1 and direct/basic calibration:

The implemented local flow is:

evaluate-cache preparation
  -> real refresh and cue --view task CLI
  -> freeze complete cue, repository evidence and answer schema
  -> deterministic prefix and current task/provenance suffix
  -> retain request body and digests without a network request
explicit run of one frozen step
  -> attempt-start journal and repository check
  -> Claude Messages API request
  -> retain raw response, timing, usage and failure state
  -> post-request repository check
summary
  -> validate retained artifacts and reconstruct delivery
  -> calculate usage, USD estimates and quality outcomes without a process or network request

The reusable prefix contains a fixed context-handling instruction and the selected item/source records, including original text, full-file/range identity and text digests. Sort deterministically; do not trim, summarize or silently drop required text. Put repository-derived text in a user content block as source material, preserving runtime instruction authority. Place an explicit cache boundary after that block. Current task text, task/target selectors, snapshot, branch/HEAD, freshness, observation time, budget and omission accounting stay in the following suffix. Retain the complete original cue separately; do not send the original source text twice. Unrelated Git metadata changes may preserve prefix bytes, but must never bypass fresh source validation.

Freeze the system instruction, answer schema, model and request settings across a comparable sequence. Hash the full reusable sequence, not just one source block. A changed selected source or declaration pin changes that identity; a local digest does not prove provider cache availability. Account for the assembled request envelope when enforcing the context budget. The existing byte-based estimate is not the model’s cache-minimum tokenizer.

The direct Messages API supports explicit content-block cache controls and non-streaming requests [4]. Use one complete response per explicit run, with no tool or follow-up loop. Use a small provider-compatible answer schema through output_config.format [5], retained and digest-bound before launch. Validate the original frozen answer contract locally as well; provider schema support never establishes source correctness or semantic compliance. Unsupported selected-model/schema combinations stop preflight rather than silently removing constraints or launching another request.

File-Level Steps

The P labels below are local to M6. P001-P006 landed in d6f94b7260f9d84b98e6b67e67dcf82b28926ac6 and are verified below. P007 remains blocked by G6. Paths marked new identify files introduced by that implementation; P008-P009 extension changes remain uncommitted.

Detailed HTTP limits, exact schema fields, CLI flags and public examples are recorded by accepted plan20261009_075715 and docs/PROMPT_CACHING.md. The locally built binary exposes these commands. Existing schema/module/storage source is unchanged, and regression checks passed. Local integration uses the actual CLI, source extraction, SQLite and HTTP adapter with only an outer TLS server.

Usage And Cost Rules

Retain the provider fields without converting absence to zero: input_tokens, cache_creation_input_tokens, cache_read_input_tokens, output_tokens, and available cache_creation lifetime counters [3]. Check that the lifetime sum agrees with aggregate cache creation when both exist. For a request with a single frozen TTL, use that declared lifetime only when the captured request and response establish a compatible interpretation; otherwise lifetime-specific cost remains unavailable.

total_input = ordinary_input + cache_write_5m + cache_write_1h + cache_read
estimated_usd = (ordinary_input * ordinary_rate
               + cache_write_5m * write_5m_rate
               + cache_write_1h * write_1h_rate
               + cache_read * read_rate
               + output * output_rate) / 1000000

When lifetime detail is unavailable, total input may still use the observed aggregate cache-creation counter exactly once; cost needs a valid lifetime allocation. Reject negative counters, overflow, incompatible units, model or rate basis, and invalid rates. Cache creation is not counted again as ordinary input, and aggregate writes are never added to their lifetime breakdown. Reasoning details, if supported, remain an output subset and are not added twice.

Observed cache reads greater than zero establish reused tokens for that request. Writes and reads may coexist. Zero observed cache activity does not identify its cause; missing counters do not establish a miss. Preserve actual response model, completion/stop state and supported request identity. A failed or truncated answer can still incur usage; retain that cost separately from task success. Missing complete usage suppresses full-attempt and sequence cost totals instead of publishing a favorable subtotal.

Measure full request wall time and preparation/CLI duration separately; non-streaming requests do not establish time to first token. Account billing, CPU, memory, filesystem I/O and task-ready latency remain not_observed. Compare complete matched cache-off request cycles against cache creation plus all observed reuses, including initial write and output costs. Report per-pair differences before descriptive aggregates and separate correctness. Changed prefix and expiry probes are separate conditions, not extra favorable samples. An observed saving applies only to the frozen conditions and reuse count.

G5 And G6 Execution Boundaries

G5 must accept the current named plan before local implementation begins. G6 is separate authority for paid requests and is required for M6 completion; it is not authority to modify code. M6 remains Blocked while either required gate is Open. If separately authorized local work begins while G6 is Open, record the actual partial progress and change the saved resume status to In progress. Local P001-P006 progress and verification are recorded below.

Propose an initial two-request cache-creation/reuse pilot under exact G6 conditions. Observe its actual counters; the first request is not guaranteed to be cold. That pilot alone cannot establish savings against a baseline. Further baseline, changed-prefix and expiry requests require the agreed continuation decision and a frozen schedule. Record request start times and the latest observed cache access when judging TTL conditions; no automatic sleep, warming, retry or continuation runs in the background. The full request count, model/API versions, TTL/minimum length, workspace scope, output limits, dated rates, assessment policy and spending controls remain pending G6. A token or request limit is not a guaranteed billing cap.

Accepted Sonnet 5.5 Extension

Plan Status: accepted Plan Acceptance: 2026-10-09; plan20261009_092451 accepted through current User continuation Implementation Authorization: 2026-10-09; auth20261010_025018; P008-P009 only Superseded Plan Artifacts: none

Decision Date: 2026-10-09. The User selected claude-sonnet-5-5 [6] during execution-plan preparation. This additive proposal does not supersede the accepted P001-P006 plan or its completed observations. That authorization does not cover this profile extension. Named proposal: plan20261009_092451 under work/review_sessions/20261009_072038_prompt-caching/plan/; its attachment sonnet55-pilot.json is proposed configuration, not a prepared request. Decision Date: 2026-10-09. The User accepted and authorized the reviewed local P008-P009 extension. Local implementation, source checks and independent implementation review are complete. C1 rev20261010_031022 and C2 rev20261010_030956 accepted the current target with zero findings/blockers; conv20261010_031713 records review 1 per lane. G6 and paid P007 remain excluded. The prior named proposal and its historical observations stay intact.

Sonnet 5.5’s default adaptive thinking differs from the current single-text- answer contract. The implemented fixed settings are thinking.type=between_tools and output_config.effort=high; without tools this model returns text [7]. Structured JSON remains the existing format [5]. Include these settings in reusable identity and retain exact older profiles’ wire bytes and identities.

Order: P008, P009 and local checks, real no-network preparation, exact G6 paid approval, then the bounded pilot portion of P007. Exact local commands remain the Planned Commands below; use GOCACHE=/tmp/repocue-m6-go-build in this environment. Capture old wire/prefix identities from the real current path before editing. New tests must fail on the missing profile/settings rather than reconstructing the answer through an internal substitute. Current recorded 4.x results do not establish Sonnet 5.5 support. No source padding, adaptive thinking/tool runtime, public schema, module or storage change is proposed. Material scope changes require a renewed plan and authority.

Proposal review observed at 2026-10-09 16:21:55 UTC: C1 rsp20261009_161608 and C2 rsp20261009_161706 each completed their first review of P008-P009 and the pilot conditions with zero findings and zero blockers. conv20261009_162155 records that review only. P008-P009 acceptance/local authority and G6 paid authority remain pending; no new profile verification or provider request occurred.

Preparation verification observed at 2026-10-09 09:29:12 UTC: the real existing build/bin/repocue evaluate-cache prepare with the proposed benchmark exited 1 with model has no supported frozen structured-output profile. The API key was removed from that process environment. DecodeSpec rejects before output directory creation and HTTP; no prepared evidence directory exists. This is the observed missing-support preflight, not a Sonnet 5.5 integration pass. make docs.build exited 0 for the updated plan document. git diff --check passed; the staged path list remained empty. The existing 25-file product digest remained 2fd82ca60fef4df964fc6b4abaf8e59eb19c721dc6ee6db04c53ee60f9d9abb6. The proposal attachment’s JSON parameter checks passed; actual successful preparation and Sonnet checks remain Pending. No broad source tests were repeated for this documentation-only preparation.

Local extension verification observed at 2026-10-10 03:05:01 UTC:

• M6 / T1, T2, T4-T7: TestCacheEvaluationShippedSonnet55Profile uses the real built CLI, Git, SQLite and only an outer TLS fixture. Before the profile edit it failed preparation with the unsupported-model error. Afterward the full shipped cache selection passed in 32.150 seconds. Exact thinking, effort, retained schema/cache boundary, changing task/Git suffix, request limits, unknown-model zero launches, model mismatch and unsuccessful thinking answer cost are covered. Synthetic USD values are software evidence only.
• M6 / T1-T7, T9: promptcache and claudeadapter count-1 checks, make check and make test.race exited 0 with Go 1.27.1. Full app suite durations were 113.465 and 189.226 seconds. CLI/Linux/Windows targets exited 0; actual Linux ELF has no INTERP and Windows artifact is x86-64 PE32+. Native Windows and actual provider behavior were not tested. Final documentation checks follow the administrative records.
• M6 / T2, T6, T9: before production edits, the old built CLI captured six legacy profiles and 24 requests under /tmp/repocue-legacy-profiles.78f2px. The new built CLI reconstructed every complete retained request byte-for-byte, including its prefix identity, and all six old/new summaries were identical. Old executable SHA-256: 0dc441ab9bee4b88c3b6b4a110bbadf962234aeed24d08059d583e601dca44e6; new: 34268a69d31c87180c50dab2f32e57c2815481191d2601986bbea5ec212ce9e8.
• Initial real Sonnet preparation passed at 2026-10-10 03:02:00 UTC under /tmp/repocue-sonnet55-pilot/cache-eval-2434897662, with the API key absent from its process environment. No run was selected. Actual benchmark, source cue, answer schema, two requests, preparation timings and complete content basis are retained. README/declaration pins remained unchanged. The initialized cache resolved to /home/jeonglee/.cache/repocue and was neither initialized, copied nor relocated. Final-state binding follows tracked record updates; this first preparation does not authorize use against a changed basis.
• The two independent implementation lanes review the frozen six-file product target via cmt20261010_030606. G6 / T8 remains Pending; no provider cache, billing, correctness/compliance assessment or savings observation exists.

Local extension review observed at 2026-10-10 03:17:13 UTC:

• C1 rev20261010_031022 and C2 rev20261010_030956 each accepted implementation review 1 of ordered six-file digest 5c15b184aba0809d6c7d33af08d36c380453424dbedcd5fc7bf5b37d99685c5d. Both have zero findings/blockers. C1 independently executed all five Sonnet subtests and the 24-request legacy reconstruction; C2 independently executed TaskCredit and the shipped task-pair test, and completed the operational documents’ second-person pass. conv20261010_031713 records the result; no correction cycle, additional feature or paid authority follows.
• make docs.build and git diff --check exited 0 at 03:12:32 UTC after the executable-identity documentation correction. Final record checks and no-model preparations follow this tracked update. The execution handoff records their actual outcomes and final content basis without another tracked edit. Codex’s empty preparation summary is not input-integrity verification; inspect its actual retained files and pins separately.
• The installed CLI’s bootstrap refresh failed during resume, before the 03:17:03 UTC status observation, with unsupported SQLite schema version 3. No cache change or repair followed. The built CLI that already prepared both initial inputs remains the planned executable. The existing initialized store stays at its configured location.

Planned Commands

These commands identify verification targets; observed results are below. Cache-specific orchestration checks reside in the actual shipped CLI tests under internal/app, including T6 and T7, rather than an evaluation-package TestCache filter with no matching tests. Existing evaluation regressions still run through make check and make test.race.

T8 commands are prepared only after exact G6 conditions exist. Build checks must inspect the actual Linux ELF/no-INTERP and Windows PE artifacts; a Windows cross-build does not establish native Windows execution.

Test Plan

Verification Results

Closure Evidence

• Local P001-P006 implementation and final T1-T7/T9 checks landed in d6f94b7260f9d84b98e6b67e67dcf82b28926ac6. Both independent implementation lanes accepted that corrected target with zero remaining blockers.
• Initial implementation reviews: C1 rev20261009_084615 accepted its lane; C2 rev20261009_084722 found F-codex_gpt6_cache_c2-001, dropped absolute HTTP timestamps needed for TTL evidence. The approved timing retention path is corrected and validated through the real CLI. Follow-ups fup20261009_085524 (C1) and fup20261009_085910 (C2) independently verify that correction and accept the local implementation; each is review 2, the single correction cycle. Final full checks also passed after correction. Root rechecked the reviewed 25-file product digest at 2026-10-09 09:01:06 UTC: 2fd82ca60fef4df964fc6b4abaf8e59eb19c721dc6ee6db04c53ee60f9d9abb6.
• G6 / T8 remains pending. No real-provider request, cache observation, account billing or real savings result exists. Synthetic TLS values verify software behavior only. M6 remains Blocked. New P008-P009 changes are uncommitted; the prior local implementation’s landing does not establish paid verification.
• ADR promotion: docs/adr/0004-provider-prompt-caching.md; operational contract: docs/PROMPT_CACHING.md. G5 acceptance does not authorize paid execution.

G5 - Prompt-Caching Plan Acceptance And Implementation Authorization

Origin: 10a4f02 / G5 GitHub Issue: none Status: Complete

Summary

Responsible party: User. Affected work: M6. Accept the reviewed integration plan, including the API boundary, reusable context rules, versioned evidence and provider-specific accounting, then separately authorize implementation. The request to register this milestone supplies neither acceptance nor implementation authority. G6 remains the independent paid-execution gate.

Completion Criteria

• The current named plan is reviewed and accepted, with unresolved API, context, schema, credential and measurement decisions made explicit.
• Review the M6 draft revision dated 2026-10-09, including the proposed text-only API slice, independent contracts, P001-P007 and T1-T9. Independent design/measurement review precedes acceptance; this drafting action supplies no such acceptance.
• Implementation authorization is recorded separately from plan acceptance. Material changes require renewed acceptance and authorization.

Verification Results

The reviewed M6/G5/G6 draft had SHA-256 a0aa66695f01ada5541510c09f3dac53b56d6035832972e0c0d74b05d5d9b81b. The two final reports and convergence are under work/review_sessions/20261009_072038_prompt-caching/. This observation changes neither the M6 plan nor its draft/acceptance/authorization fields at that earlier observation. At that time all M6 / T1-T9 remained Pending and no implementation, paid request or saving was established. Current local observations are in M6. At the earlier observation, exact schema fields/examples, CLI flags and HTTP limits remained unresolved. The later accepted named plan serializes those details within the reviewed architecture. Decision Date: 2026-10-09. The original local P001-P006 implementation is authorized. The later Sonnet 5.5 selection does not authorize the proposed P008-P009 profile extension or G6 paid calls.

Closure Evidence

• Decision Date: 2026-10-09. Accepted plan20261009_075715 and separately authorized local P001-P006 through auth20261009_075715. G6 remains excluded.

G6 - Claude API Experiment Conditions And Cost Authorization

Origin: 10a4f02 / G6 GitHub Issue: none Status: Open

Summary

Responsible party: User. Affected work: M6 / T8. Authorize the exact paid Claude API experiment independently of local implementation. Freeze provider and model/API versions, repository/task/prefix identity, cache policy and TTL, model minimum length, request order/count, dated API rates, evidence location, task-quality assessment, spending controls and continuation conditions.

Completion Criteria

• Exact executable conditions distinguish baseline, write, reuse, changed prefix and expiry observations. No hit or miss is inferred from request order alone; the collection path retains provider usage and failed attempts.
• The User authorizes the initial bounded request set and its maximum planned cost. State any inability to enforce a hard billing ceiling; a run-count checkpoint is not a guaranteed spending cap. No automatic retry follows.
• Subsequent paid requests require the agreed continuation decision. G1 and G3 do not authorize this provider or experiment.

Verification Results

Proposed Initial Execution Conditions

Proposal Date: 2026-10-09. Acceptance: none. Paid Execution Authorization: none. Named proposal: plan20261009_092451. Sonnet 5.5 local support P008-P009 is accepted and authorized through auth20261010_025018. Implementation and local checks passed, initial actual no-model preparation succeeded, and both independent implementation reviews accepted the target. Final-state request binding follows this tracked update; consult the execution handoff’s actual prepared identities and result before considering paid authority. G6 remains Open and M6 / T8 remains Pending.

Recheck README.md digest sha256:7ffa93ebe3f4cd35a600443026f79f8476b18e885bcb48bf5635e41faa15669e and declaration digest sha256:8f2d88708fc9afac9ce2a3a6b9a21881f9dc0e35028b703b6b83ec36fc924d59 at real preparation. Freeze actual dirty repository basis, source/schema/ benchmark/wire/prefix identities and executable after all local changes. Resolve and record the already initialized maintained cache root; no implicit init, rebaseline, copy or repair. Confirm one workspace/key scope for both requests without retaining the credential. Exact prepared identities and that operator confirmation remain prerequisites for paid authorization.

Sonnet 5.5 has a 512-token cache minimum [6]. RepoCue’s byte estimate does not prove eligibility. Do not add filler or request token counting implicitly. After the first response, summarize and stop on HTTP/answer/basis failure, unknown cost, incomplete usage, model mismatch, timeout, no observed cache activity or total input above the 8000-token planning scenario. Retain the failed attempt. For conditional continuation, reprice the observed first total input as full 5m write plus 512 output tokens; first observed cost plus that second-call reserve must fit USD 0.10. This checkpoint is not a bill guarantee.

If separately authorized to continue, send the second request after the first completes, preferably within 60 seconds, and before the first observed cache write/read HTTP start plus five minutes. TTL starts at request start [3]. Stop if the window cannot be met. No retry, automatic wait/warming, replacement preparation or additional call is included. The first request may already read cache; report actual counters, never infer cold creation or reuse from order.

Illustrative no-hit scenario: two requests, each with 8000 actual input tokens all priced as 5m writes and 512 output tokens, cost 2 * (8000 * 2.50 + 512 * 10.00) / 1000000 = USD 0.05024 [8]. This is a conditional planning calculation, not observed usage, an invoice or a billing bound. Actual provider tokenization/formatting overhead and account conditions remain unverified.

Retain all attempts and separate source delivery, discovery ID correctness, claim correctness and instruction compliance. Missing independent assessment remains not_observed; no paid assessor is included. This pilot can establish observed cache activity only. It has no matched baseline and leaves the full baseline/change/expiry checks, savings, billing, task-ready latency and M6 closure unestablished. Further requests require a separate exact continuation plan and authority.

Closure Evidence

• none

Backlog

Work

Backlog Details

No unassigned work is recorded.

References

[1] OpenAI. “Pricing.” ChatGPT Learn. Accessed: Sep. 8, 2026. [Online]. Available: https://learn.chatgpt.com/docs/pricing

[2] OpenAI. “GPT-5.6 Luna Model.” OpenAI API. Accessed: Sep. 8, 2026. [Online]. Available: https://developers.openai.com/api/docs/models/gpt-5.6-luna

[3] Anthropic. “Prompt caching.” Claude Platform Docs. Accessed: Oct. 8, 2026. [Online]. Available: https://platform.claude.com/docs/en/build-with-claude/prompt-caching

[4] Anthropic. “Create a Message.” Claude API Reference. Accessed: Oct. 9, 2026. [Online]. Available: https://platform.claude.com/docs/en/api/messages/create

[5] Anthropic. “Structured outputs.” Claude Platform Docs. Accessed: Oct. 9, 2026. [Online]. Available: https://platform.claude.com/docs/en/build-with-claude/structured-outputs

[6] Anthropic. “Claude Sonnet 5.5.” Claude Platform Docs. Accessed: Oct. 9, 2026. [Online]. Available: https://platform.claude.com/docs/en/models/sonnet-5-5/overview

[7] Anthropic. “Claude Sonnet 5.5 migration guide.” Claude Platform Docs. Accessed: Oct. 9, 2026. [Online]. Available: https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide

[8] Anthropic. “Pricing.” Claude Platform Docs. Accessed: Oct. 9, 2026. [Online]. Available: https://platform.claude.com/docs/en/about-claude/pricing

RepoCue — Project Background, Goals, Architecture, and Bootstrap Specification

1. Project Name

RepoCue

RepoCue is a local, agent-independent repository context cache for AI coding agents.

The name “Cue” reflects the primary goal: give an AI agent just enough current repository information to begin useful work immediately, without repeatedly re-reading and rediscovering the repository from scratch.

A concise description:

RepoCue maintains a compact, current, locally cached understanding of a Git repository and serves token-efficient context to multiple AI agents.

A shorter tagline:

Read once. Refresh incrementally. Cue every agent.

2. Background

Modern AI coding agents such as Codex CLI, Claude Code, Cursor agents, and other MCP-capable tools frequently begin work by rediscovering the repository.

A typical agent session may perform some variation of:

git status
git log
find / tree
read README
read AGENTS.md
search architecture docs
inspect package manifests
grep symbols
read core source files
inspect tests
infer module relationships
inspect recent diffs

This is often necessary because the agent has no persistent, trustworthy view of the repository’s current state.

The same repository may therefore be independently rediscovered:

• by multiple agents;
• by multiple sessions of the same agent;
• after relatively small code changes;
• after restarting an agent;
• after switching between tools;
• after a context window is compacted or discarded.

The result is repeated consumption of:

• LLM input tokens;
• agent reasoning tokens;
• file reads;
• grep/search operations;
• Git commands;
• tool calls;
• CPU time;
• filesystem I/O;
• latency before useful work begins.

For a repository that changes incrementally, repeatedly rebuilding the same high-level understanding is wasteful.

RepoCue is intended to remove as much of this repeated discovery cost as possible.

3. Core Problem

The problem is not simply “how to summarize a Git repository.”

Existing tools can already:

• pack repositories into a context file;
• generate code maps;
• index symbols;
• search source code;
• expose repositories through MCP;
• maintain embeddings;
• summarize documentation.

The specific problem RepoCue targets is:

How can the current state of a repository be maintained locally, refreshed cheaply, and communicated to many AI agents with the minimum practical token and latency cost while preserving sufficient accuracy and freshness for real work?

RepoCue therefore focuses on persistent current state, incremental refresh, multi-agent reuse, controlled rebaseline, and measurable resource savings.

4. Primary Goal

RepoCue’s primary goal is:

Automatically or manually maintain the current state of a Git repository locally and provide the freshest useful repository context to diverse AI agents with minimal tokens and minimal latency, thereby minimizing the repeated token, tool-call, compute, memory, and I/O costs associated with asking each agent to rediscover “the current state” of the repository.

The optimization target is not merely smaller output.

RepoCue should optimize the total cost required for an agent to become task-ready.

5. Core Principle

The project can be summarized as:

Read once
    ↓
Establish baseline
    ↓
Refresh incrementally
    ↓
Rebaseline intentionally
    ↓
Serve many agents
    ↓
Measure whether this is actually cheaper and still correct

Another useful formulation:

Index once, update incrementally, reset intentionally, serve many, and measure the savings without sacrificing context quality.

6. What “Current Repository State” Means

“Current state” is broader than git status.

RepoCue should eventually understand several classes of repository state.

6.1 Git State

Examples:

• repository identity;
• current branch;
• HEAD commit;
• tags;
• dirty/clean working tree;
• staged changes;
• unstaged changes;
• untracked files;
• recent commits;
• changes since the current baseline;
• changes since a specified snapshot.

6.2 Code Structure

Examples:

• directory/module structure;
• languages;
• entry points;
• packages;
• important modules;
• public symbols;
• classes/functions/methods;
• signatures;
• imports;
• references;
• dependency relationships;
• test relationships;
• configuration relationships.

The initial implementation should favor deterministic structural analysis using Git, filesystem metadata, Tree-sitter, language tooling, or similar mechanisms rather than LLM analysis whenever possible.

6.3 Documentation State

Examples:

• README files;
• AGENTS.md or equivalent agent instructions;
• architecture documents;
• ADRs;
• design documents;
• installation documentation;
• release documentation;
• roadmap/milestone documents;
• API documentation;
• documentation-to-code relationships;
• potentially stale documentation.

RepoCue should distinguish between:

document exists
document is important
document describes entity X
document changed
related code changed
document may now be stale

A document should not automatically be declared stale merely because related code changed. The system should preserve confidence and evidence.

6.4 Operational State

Where available:

• test status;
• build status;
• lint/static analysis state;
• generated artifacts;
• known TODO/FIXME markers;
• repository-local configuration;
• active development areas.

This category should remain extensible and should not block the MVP.

7. Key Design Decision: RepoCue Is a Cache, Not a Historical Archive

RepoCue does not need to permanently preserve every historical repository state.

Git already provides source history.

RepoCue’s job is to maintain the most useful current contextual understanding.

Default retention should favor:

current baseline
+
current state
+
short rolling delta history
+
explicitly pinned checkpoints

It should not keep unlimited snapshots by default.

8. Core Terminology

RepoCue should use the following terminology consistently.

8.1 Epoch

An epoch is a context-validity period with a common baseline.

Typical epoch boundaries include:

• a release change;
• a milestone;
• a major architecture transition;
• a user-requested reset;
• a tag selected as a new reference point.

Example:

epoch: release:1.3.0

8.2 Baseline

A baseline is the result of a full repository analysis.

This is the “read once” state.

A baseline may include:

• repository structure;
• core symbols;
• dependency relationships;
• important documentation;
• derived summaries;
• repository facts;
• metadata required for incremental updates.

8.3 Rebaseline

A rebaseline discards the assumption that the previous baseline remains the best foundation and performs a new full analysis.

Rebaseline must be available manually.

Typical triggers:

new release
new milestone
major refactor
large branch change
cache integrity concern
user request
significant context drift

Example CLI:

repocue rebaseline --reason release-change --label release:1.4.0

8.4 Snapshot

A snapshot identifies a coherent repository-context state at a point in time.

A snapshot does not necessarily duplicate all data. It may reference the current baseline plus accumulated deltas.

8.5 Delta

A delta records meaningful changes since another RepoCue state.

During the baseline and incremental-refresh stages, file-level operations such as file.content_changed and file.metadata_changed are repository-state semantic deltas. They describe the meaning of a repository state transition, not code-symbol semantics. Symbol, dependency, and document semantic operations may be added later without renaming the file-level operations.

The external delta should be semantic when possible.

Example:

{
  "op": "symbol.signature_changed",
  "entity": "symbol:Runner.start",
  "before": "start(config)",
  "after": "start(config, wait=false)"
}

rather than merely exposing raw JSON paths.

8.6 Checkpoint

A checkpoint is a deliberately retained state.

Examples:

• release;
• milestone;
• Git tag;
• architecture transition;
• user-pinned state.

Checkpoint retention differs from normal rolling deltas.

8.7 Cue

A cue is the small agent-facing context projection RepoCue returns.

A cue is not the database and not the entire snapshot.

It is a token-budgeted view selected for a purpose.

Examples:

overview cue
delta cue
structure cue
symbol cue
documentation cue
task-specific cue

9. Update Model

RepoCue must support both automatic and manual updates.

9.1 Manual Refresh

repocue refresh

This should:

1. inspect the repository state;
2. identify changed files;
3. update only affected structural/document/state records where practical;
4. create or advance the current snapshot;
5. record refresh metrics.

9.2 Automatic Refresh

Potential mechanisms:

• filesystem watcher;
• Git hooks;
• periodic local polling;
• explicit integration with agent/tool activity.

Potential Git hook points:

post-commit
post-checkout
post-merge
post-rewrite

Automatic refresh must avoid excessive work during rapid edit sequences.

A debounce or batching mechanism is desirable.

9.3 Manual Full Read / Rebaseline

The user must always be able to say:

repocue rebaseline

or:

repocue rebaseline --label milestone:systemd-migration

This performs a new full analysis and establishes a fresh baseline.

9.4 Release Change

A release transition should normally create a new epoch.

Example:

release 1.3 epoch
  baseline
  delta
  delta
  delta

release 1.4 begins
  optional pin of old release state
  new full baseline
  new epoch

RepoCue should support automatic detection heuristics but should not make destructive retention decisions solely from heuristics without clear policy.

10. Retention Model

Default:

Current epoch
├── baseline
├── current snapshot
└── rolling recent deltas

Pinned checkpoints
├── release:1.3.0
├── milestone:systemd-migration
└── tag:v2.0.0

Suggested configurable policy:

retention:
  rolling_deltas: 20
  keep_current_baseline: true
  keep_pinned_checkpoints: true
  prune_unpinned_previous_epochs: true

The exact policy should remain configurable.

11. Agent Independence

RepoCue must not be designed as a Codex-specific plugin.

It should be usable by:

• Codex CLI;
• Claude Code;
• Cursor;
• IDE agents;
• custom autonomous agents;
• future MCP-compatible clients;
• scripts and CI tools.

The same cached repository understanding should be reusable across all of them.

This is a fundamental project value.

12. Canonical Architecture

Recommended architecture:

                        Git Repository
                              │
                ┌─────────────┴─────────────┐
                │                           │
            Git analyzer              Source/Doc indexers
                │                           │
                └─────────────┬─────────────┘
                              │
                        Context Engine
                              │
                 entities + relations + facts
                              │
                              ▼
                         Local Store
                           SQLite
                              │
                 ┌────────────┴────────────┐
                 │                         │
             Cue Projector             Evaluator
          scope/rank/budget          metrics/experiments
                 │
                 ▼
               MCP / CLI
                 │
        ┌────────┼─────────┐
        ▼        ▼         ▼
      Codex    Claude    Agent N

13. Canonical Data Model

The internal semantic model should be a lightweight typed property graph.

A graph database is not required for the first implementation.

SQLite tables can model entities and relations efficiently enough.

13.1 Entity Examples

repository
directory
file
module
symbol
document
test
configuration
build_target
release
milestone

Example:

{
  "id": "symbol:src/runner.py:Runner.start",
  "kind": "symbol",
  "subkind": "method",
  "name": "Runner.start",
  "path": "src/runner.py",
  "signature": "start(config: Config) -> Process",
  "content_digest": "sha256:...",
  "summary": "Starts an IOC process"
}

13.2 Relation Examples

contains
defines
imports
calls
references
depends_on
documents
tests
configures
changed_by
affected_by
supersedes

Example:

{
  "source": "doc:docs/architecture.md",
  "type": "documents",
  "target": "module:runner",
  "confidence": 0.93,
  "evidence": ["docs/architecture.md"]
}

14. Local Storage

Recommended MVP storage:

SQLite

Potential supporting features:

• FTS5 for text search;
• JSON columns where useful;
• content hashes;
• indexes on entity IDs, paths, snapshot IDs, and relationships.

Suggested initial logical tables:

repositories
epochs
baselines
snapshots

entities
relations
documents
facts

deltas
delta_items

checkpoints
checkpoint_items

refresh_runs
evaluation_runs
evaluation_metrics

Do not over-normalize the MVP prematurely.

Correctness, inspectability, and migration simplicity are more important than theoretical schema elegance.

15. Agent-Facing Format

The canonical agent interchange format should be:

Versioned structured JSON validated by JSON Schema

Markdown should be generated as an optional human-readable view rather than used as the source of truth.

Example envelope:

{
  "schema_version": "repocue/1.0",
  "kind": "overview",
  "repo": "example-repo",
  "epoch": "release:1.4.0",
  "snapshot": "s203",
  "basis": {
    "head": "71cf90a",
    "dirty": false
  },
  "freshness": {
    "status": "current"
  },
  "budget": {
    "max_tokens": 500,
    "estimated_tokens": 418
  },
  "summary": {
    "purpose": "Example repository",
    "architecture": [
      "cli -> config -> runner",
      "runner -> environment"
    ]
  },
  "warnings": [],
  "more": []
}

Important top-level concepts:

schema_version
kind
repo
epoch
snapshot
basis
freshness
budget
content
warnings
references/more

16. Progressive Disclosure

RepoCue must not send all repository context merely because it is available.

The preferred information path is:

manifest
   ↓
overview
   ↓
delta or focused structure
   ↓
specific entity/document
   ↓
original source only when necessary

Example approximate targets:

manifest               50–150 tokens
overview              250–600 tokens
recent delta           50–500 tokens
focused structure     200–800 tokens
focused entity        100–500 tokens

These are initial hypotheses, not hard requirements.

They must be evaluated empirically.

17. Freshness and Trust

A compact context cache is dangerous if the agent cannot tell whether it is current.

Every meaningful cue should identify its basis.

Example:

{
  "epoch": "release:1.4.0",
  "snapshot": "s203",
  "indexed_head": "71cf90a",
  "working_tree_state": "clean",
  "observed_at": "2026-08-27T20:00:00-07:00",
  "freshness": "current"
}

If RepoCue cannot guarantee freshness, it should say so.

Possible states:

current
dirty-but-indexed
refresh-needed
possibly-stale
invalid
unknown

RepoCue should prefer explicit uncertainty over false confidence.

18. Documentation Freshness

Documentation state is important but must be handled carefully.

Potential status model:

current
likely-current
possibly-stale
stale-confirmed
unknown

Deterministic signals may include:

• related code changed after the document;
• referenced files/symbols disappeared;
• documented signature differs from code;
• paths no longer exist;
• release version mismatch.

Semantic judgment may eventually use an LLM, but LLM usage should be optional and bounded.

The MVP should begin with deterministic evidence wherever possible.

19. LLM Usage Policy

RepoCue itself should minimize its dependence on LLMs.

Prefer deterministic extraction for:

Git state
filesystem structure
symbols
signatures
imports
references
hashes
change detection
test metadata
document paths
explicit links

Optional LLM usage may later assist with:

architecture summarization
document-to-code semantic linkage
change impact summaries
staleness judgment
task-specific context synthesis

If an LLM is used, RepoCue should measure and report that cost as part of its own maintenance cost.

Otherwise the system could appear to save agent tokens while silently spending similar resources during cache generation.

20. MCP Interface

RepoCue should expose its information through MCP for multi-agent interoperability.

The MCP interface should remain small.

Recommended initial tools:

context_get
context_search
context_refresh
context_rebaseline

20.1 context_get

Possible views:

manifest
overview
delta
structure
entity
document
task_context

Example request:

{
  "view": "overview",
  "max_tokens": 500
}

Example delta request:

{
  "view": "delta",
  "since_snapshot": "s198",
  "max_tokens": 400
}

20.2 context_search

Example:

{
  "query": "IOC startup lifecycle",
  "scope": ["code", "docs"],
  "max_results": 8,
  "max_tokens": 700
}

20.3 context_refresh

Example:

{
  "mode": "incremental"
}

20.4 context_rebaseline

Example:

{
  "reason": "release-change",
  "label": "release:1.4.0",
  "pin_previous": true
}

MCP resources may later expose stable read-only URIs such as:

repocue://<repo>/overview/current
repocue://<repo>/snapshot/<id>
repocue://<repo>/delta/<from>/<to>
repocue://<repo>/entity/<id>
repocue://<repo>/document/<id>
repocue://<repo>/checkpoint/<id>

21. CLI Interface

Initial CLI proposal:

repocue init
repocue status
repocue refresh
repocue watch

repocue cue
repocue cue --view overview
repocue cue --since s198
repocue cue --max-tokens 500

repocue search "startup lifecycle"

repocue rebaseline
repocue rebaseline --label release:1.4.0
repocue rebaseline --reason architecture-refactor

repocue checkpoint list
repocue checkpoint pin --label milestone:systemd-migration
repocue checkpoint delete <id>

repocue serve
repocue evaluate
repocue metrics

The exact CLI should evolve after the smallest vertical slice is validated.

22. Evaluation Is a Core Product Requirement

RepoCue must not claim success merely because its output is compact.

The system must quantitatively measure resource savings and qualitatively evaluate context quality.

The fundamental experiment is:

Compare an agent that directly rediscovers the repository with an agent that uses RepoCue, using the same repository, model, and task.

23. Quantitative Metrics

At minimum evaluate:

23.1 Token Metrics

direct discovery input tokens
RepoCue cue tokens
RepoCue maintenance LLM tokens, if any
total tokens per completed task

Important derived metrics:

gross context token reduction
net total token reduction

23.2 Task-Ready Latency

Measure time from agent start to the point where the agent has enough repository understanding to begin the requested task.

This may require a practical operational definition.

23.3 Repository Reads

Count repository exploration operations attributable to current-state discovery.

Examples:

file reads
grep/search calls
tree/find operations
git inspection calls
bytes read
files scanned

23.4 Tool Calls

Measure tool-call count before useful implementation begins and across the whole task.

23.5 Cache Maintenance Cost

Measure:

refresh duration
CPU usage
memory usage
filesystem bytes read
filesystem bytes written
storage footprint

23.6 Freshness Lag

Measure:

repository change time
→
RepoCue current-state availability time

23.7 Reuse

Measure:

agents per baseline
sessions per baseline
cues served per refresh

23.8 Rebaseline Cost

Measure full reanalysis cost.

This is important for determining when incremental maintenance stops being cheaper than a new baseline.

23.9 Break-Even Point

Define:

B = baseline creation cost
U = incremental maintenance cost
D = direct repository discovery cost per agent/session
C = RepoCue cue cost per agent/session
N = number of consumers

Compare:

Direct total:
N * D

RepoCue total:
B + U + N * C

Estimate the reuse count at which RepoCue becomes cheaper.

24. Context Quality Metrics

Efficiency is meaningless if important context is lost.

Evaluate:

accuracy
completeness
freshness
relevance
noise
stale-context error rate
agent correction rate

Possible qualitative dimensions:

• architecture understanding;
• current-state understanding;
• documentation awareness;
• recent-change awareness;
• task correctness;
• uncertainty handling;
• context usability;
• trustworthiness.

25. Failure Taxonomy

Track failures by category.

Initial taxonomy:

missing-context
stale-context
incorrect-summary
over-compression
noisy-context
scope-confusion
invalid-delta
bad-document-link
false-freshness
rebaseline-too-late
rebaseline-too-often

A useful evaluation report should be able to say things such as:

Token use fell by 84%, but public API impact was omitted in 6% of tested changes.

or:

RepoCue had little benefit for a one-shot small repository, but became substantially cheaper after the second independent agent session.

or:

Incremental refresh was effective for small commits, while a full rebaseline was cheaper after a large architecture migration.

26. Non-Goals

RepoCue is not initially intended to be:

• a replacement for Git;
• a complete source-code database;
• a permanent archive of every context state;
• a replacement for reading source code when implementation detail is required;
• a generic vector database;
• a hosted SaaS service;
• a Codex-only plugin;
• a Claude-only plugin;
• an autonomous coding agent;
• a repository packer that dumps the entire codebase into a prompt;
• an LLM-first repository summarizer.

RepoCue should help an agent decide what it already needs to know and what it still needs to inspect.

27. Security and Privacy

Default behavior should be local-first.

Do not transmit repository content to a remote service unless explicitly enabled.

Consider:

• .gitignore;
• secrets;
• generated files;
• binary files;
• private keys;
• credential files;
• vendor directories;
• build outputs.

The indexer should support exclusion rules.

No remote LLM dependency should be required for basic functionality.

28. Proposed Local Layout

Repository-local configuration:

<repo>/
└── .repocue/
    └── config.yaml

Local state outside the repository:

~/.cache/repocue/
└── <repo-id>/
    ├── state.db
    ├── objects/
    └── logs/

Reasons:

• cache data does not pollute source control;
• multiple agents share the same local state;
• repository config may optionally be committed;
• cache can be deleted and rebuilt;
• checkpoints can remain local unless explicit export is requested.

29. Suggested Configuration

Example:

schema_version: 1

repository:
  include:
    - src/**
    - tests/**
    - docs/**
    - README*
    - AGENTS.md
  exclude:
    - .git/**
    - build/**
    - dist/**
    - node_modules/**
    - vendor/**

refresh:
  mode: manual
  watch_debounce_ms: 1500

retention:
  rolling_deltas: 20
  prune_unpinned_epochs: true

cue:
  default_max_tokens: 500

analysis:
  llm_enabled: false

evaluation:
  enabled: true

30. MVP Philosophy

Do not build the full vision before testing the core hypothesis.

The first implementation should prove:

A locally maintained repository baseline plus incremental Git/file updates can materially reduce repeated agent repository discovery without materially harming task readiness.

The MVP should be narrow.

31. Proposed MVP

Phase 0 — Repository Bootstrap

Create:

README.md
LICENSE
pyproject.toml or equivalent
src/
tests/
docs/

Add architecture and schema documents before heavy implementation.

Phase 1 — Git + Filesystem Baseline

Support:

repocue init
repocue status
repocue rebaseline
repocue refresh
repocue cue --view manifest
repocue cue --view overview

Baseline should capture:

• repository root;
• branch;
• HEAD;
• dirty state;
• tracked files;
• file sizes;
• file digests;
• directory structure;
• identified documentation;
• language/file-type distribution.

No LLM required.

Phase 2 — Incremental Refresh

Detect changed files using Git and hashes.

Update only affected records.

Persist:

• baseline;
• current snapshot;
• rolling deltas.

Support:

repocue cue --since <snapshot>

Phase 3 — Structural Code Index

Add Tree-sitter or an equivalent parsing layer.

Capture:

• symbols;
• signatures;
• imports;
• basic relationships.

Start with a limited set of languages if necessary.

Architecture must allow additional language adapters.

Phase 4 — Documentation Relationships

Index key documentation.

Start with deterministic relationships:

• explicit file/path references;
• symbol names;
• headings;
• repository links.

Add conservative freshness warnings.

Phase 5 — MCP Server

Expose current RepoCue data to external agents.

Start with:

context_get
context_refresh
context_rebaseline

Add search only after basic retrieval is stable.

Phase 6 — Evaluation Harness

Implement repeatable measurements comparing:

direct repository discovery
vs
RepoCue-assisted discovery

The evaluation framework should be developed early enough that design decisions can be measured rather than guessed.

32. First Vertical Slice

The first meaningful end-to-end demonstration should be:

1. Initialize RepoCue in a Git repository.
2. Perform one deterministic baseline scan.
3. Store it in SQLite.
4. Report repository and RepoCue status.
5. Produce a compact JSON overview cue within a requested token budget.
6. Detect changed files and run an incremental refresh.
7. Produce a semantic delta from a previous snapshot.
8. Rebaseline manually into a new epoch.
9. Measure duration, files scanned, bytes scanned, database size, cue bytes,
   and estimated cue tokens.
10. Maintain transactional consistency and explicit freshness and basis
    metadata.

Do not require MCP or Tree-sitter for this first slice.

The point is to establish the state model and measurement framework first.

The first slice retains a superseded epoch and its snapshots and deltas. It does not implement checkpoint management, physical pruning, or retention-policy enforcement. Those capabilities belong to the next storage-lifecycle milestone, after the core state model is validated.

33. Important Architectural Constraints

33.1 Stable IDs

Entities need stable identifiers where practical.

Do not use database row IDs as public identities.

Example:

file:src/runner.py
module:src.runner
symbol:src/runner.py:Runner.start
doc:docs/architecture.md

33.2 Content Hashing

Use content digests to avoid unnecessary reparsing.

33.3 Schema Versioning

All external structured outputs must carry a schema version.

33.4 Migration Support

SQLite schema changes should eventually use explicit migrations.

33.5 Deterministic Output

For a given repository state and configuration, deterministic portions of the cue should be stable.

Stable ordering helps:

• testing;
• diffability;
• prompt caching;
• reproducibility.

33.6 Token Budget

Token budgeting should be a first-class API concept.

Do not simply generate unlimited structured content and truncate arbitrary bytes.

Ranking and selection should happen before serialization.

33.7 Provenance

Derived facts should retain enough evidence to be inspected.

Example:

{
  "fact": "docs/install.md may be stale",
  "confidence": 0.72,
  "evidence": [
    "src/install.py changed after document",
    "document references removed option --legacy"
  ]
}

34. Research Questions

The implementation should preserve the ability to answer these questions empirically:

1. How much repository discovery cost is repeated across agent sessions?
2. How much of that cost can RepoCue eliminate?
3. How small can a useful initial cue be?
4. When does aggressive compression begin harming task quality?
5. How frequently should incremental refresh occur?
6. When is rebaseline cheaper or safer than continuing incremental updates?
7. How many agent/session reuses are required to amortize baseline cost?
8. Does a shared context cache improve consistency between different agents?
9. How accurately can documentation freshness be estimated without an LLM?
10. What fraction of repository state can be maintained deterministically?
11. Which context categories produce the highest marginal value per token?
12. Does agent-driven follow-up retrieval outperform a larger initial cue?
13. What is the stale-context failure rate under realistic development activity?
14. How does RepoCue perform on small, medium, and very large repositories?
15. How much CPU/I/O overhead does maintaining the cache impose?

35. Acceptance Criteria for the First Vertical Slice

The first vertical slice is successful when it can demonstrate all of the following on a real Git repository:

Functional

• initialize repository metadata;
• perform a full baseline scan;
• persist the state locally;
• identify current Git HEAD and dirty state;
• report repository and RepoCue status;
• perform an incremental refresh;
• create a new snapshot;
• generate a compact overview;
• generate changes since a previous snapshot;
• manually rebaseline;
• start a new epoch;
• mark the previous epoch inactive or superseded without deleting it;
• commit each state transition transactionally.

Performance / Measurement

The tool reports at least:

baseline duration
refresh duration
files scanned
bytes scanned
database size
cue byte size
estimated cue tokens

Quality

The output clearly exposes:

which commit/state it represents
whether it is current
what is known
what is uncertain
what changed
where more detail can be obtained

Pinned checkpoints, pruning of unpinned historical state, checkpoint CLI commands, and retention-policy enforcement are outside this acceptance scope.

36. Implementation Guidance for Codex

When implementing this project:

1. Do not expand scope unnecessarily.
2. Do not begin with an LLM integration.
3. Do not begin with embeddings.
4. Do not begin with a graph database.
5. Use SQLite first.
6. Keep domain models independent of SQLite representations.
7. Make refresh/rebaseline behavior explicit and testable.
8. Treat measurement as part of the architecture, not an afterthought.
9. Prefer deterministic repository facts.
10. Keep agent-facing schema small, stable, and versioned.
11. Avoid creating large generated Markdown context files as canonical state.
12. Markdown may be generated as a view.
13. Keep MCP as an adapter over the core service, not the core itself.
14. Design so another transport can be added later.
15. Do not commit or push unless explicitly instructed by the user.

37. Recommended Initial Technical Choices

These are recommendations, not irreversible requirements.

Language

Go is the primary implementation language because:

• low startup latency and memory overhead;
• straightforward Git, filesystem, SQLite, and JSON integration;
• simple concurrency for later background refresh;
• simple cross-platform distribution as a single executable;
• suitable MCP support for a later adapter;
• direct measurement and profiling support.

Prefer the Go standard library where practical. SQLite should use database/sql with a CGo-free driver so normal distribution does not require a C compiler or a separate runtime. Keep the driver isolated inside the storage package so measurements can justify a later change.

Storage

SQLite

Serialization

JSON

Schema

JSON Schema

Configuration

YAML or TOML

CLI

Use a small mature CLI framework or standard library if sufficient.

Testing

Use unit tests plus repository fixtures.

Integration tests should initialize temporary real Git repositories.

38. Suggested Repository Structure

One possible starting structure:

repocue/
├── AGENTS.md
├── README.md
├── LICENSE
├── go.mod
│
├── docs/
│   ├── PROJECT_BRIEF.md
│   ├── ARCHITECTURE.md
│   ├── DATA_MODEL.md
│   ├── EVALUATION.md
│   └── ROADMAP.md
│
├── cmd/
│   └── repocue/
│       └── main.go
│
└── internal/
    ├── app/
    ├── repository/
    ├── storage/
    ├── snapshot/
    ├── cue/
    └── metrics/

Use package-level tests and temporary real Git repositories. Do not create every package immediately merely because it appears in this tree.

Create modules as required by the vertical slice.

39. Suggested Initial AGENTS.md

Keep AGENTS.md short because every agent may repeatedly consume it.

Example:

# RepoCue Agent Instructions

RepoCue is a local repository-context cache for AI coding agents.

Authoritative project specification:
`docs/PROJECT_BRIEF.md`

Core invariants:

- Maintain current repository context locally.
- Prefer incremental refresh over repeated full analysis.
- Support explicit manual rebaseline.
- Begin a new epoch for release/milestone resets when appropriate.
- Keep current state + short rolling deltas + pinned checkpoints; do not retain unlimited context history by default.
- Serve small, versioned, freshness-aware cues to multiple agents.
- Optimize total task-ready cost, not merely serialized output size.
- Measure token, latency, tool-call, CPU, memory, I/O, freshness, reuse, and context-quality outcomes.
- Prefer deterministic extraction; LLM use must be optional and measured.
- SQLite is the initial canonical local store.
- Structured JSON is the canonical agent interchange format.
- MCP is an adapter over the core, not the core architecture.
- Do not commit or push unless explicitly requested.

40. First Task for Codex

After reading this specification, Codex should not immediately implement the entire system.

The first task should be:

Review this specification for internal contradictions, hidden assumptions, and decisions that would block the first vertical slice. Record only material issues. Then create the minimum repository skeleton and implement a deterministic Phase-1 prototype that can baseline a Git repository into SQLite, report status, create a compact JSON overview cue, perform a changed-file incremental refresh, and manually rebaseline into a new epoch while retaining the superseded epoch. Add metrics for duration, files scanned, bytes scanned, database size, output bytes, and estimated output tokens. Keep checkpoint management, pruning, retention-policy enforcement, MCP, Tree-sitter, embeddings, and LLM integration out of the first implementation unless a minimal abstraction is needed to avoid a clear architectural dead end.

The prototype should be runnable locally.

Suggested demonstration:

repocue init .
repocue status
repocue cue --view overview --max-tokens 500

# modify repository

repocue refresh
repocue cue --since <previous-snapshot>

repocue rebaseline --label milestone:first-prototype
repocue metrics

41. Questions Codex Should Resolve During Bootstrap

Codex may make reasonable implementation choices, but it should explicitly document decisions that materially affect the model.

Examples:

1. How is repository identity generated?
2. How are stable entity IDs represented?
3. What exactly makes two snapshots distinct?
4. How is working-tree state represented when HEAD has not changed?
5. What is the minimum data retained for a rolling delta?
6. How is token count estimated?
7. What does current freshness mean operationally?
8. How are ignored/generated/binary files handled?
9. How are schema migrations handled?
10. How should interrupted refreshes remain transactional?

Document answers in ADR-style short decisions where appropriate.

Safe pruning policy and pinned checkpoint representation are deferred to the storage-lifecycle milestone and must not be enforced by the first slice.

42. Principle for Future Design Decisions

When deciding whether to add a feature, ask:

Does this feature measurably reduce the repeated cost of making AI agents understand the repository’s current state, while preserving or improving correctness and freshness?

If the answer is unclear, measure before expanding the architecture.

RepoCue’s value is not the size of its index.

RepoCue’s value is the avoidable repository-understanding work that agents no longer have to repeat.

43. Core Evaluation & Hardening Milestone

The accepted first vertical slice is followed by Core Evaluation & Hardening. This milestone validates the central hypothesis before functionality expands:

Does maintained repository context materially reduce the total resources required for an AI agent to understand the repository’s current state?

43.1 State-Model Hardening

Integration coverage uses temporary real Git repositories and includes:

modified tracked files
staged changes
untracked files
renames
deletions
ignored files
binary files
no-op refresh
branch changes
detached HEAD
dirty rebaseline
failed refresh
interrupted refresh

A failed or interrupted refresh must not expose a partially-current snapshot.

Scan operating assumption (Decision Date: 2026-09-06): the repository’s files and Git state remain unchanged for the duration of each scan. A scan captures its Git basis once before reading files; it does not repeat repository-wide Git or filesystem checks to detect concurrent mutations. observed_at records that initial basis capture. Freshness is conditional on this assumption. Changes between separate scans remain detectable. If another process writes during a scan, rerun refresh after it finishes; the scan does not guarantee that such a mutation will be rejected.

SQLite transactions and expected-current-snapshot checks still protect publication against failed writes and concurrent RepoCue state transitions. Evaluation still checks repository state before and after each agent run; the scan assumption does not permit an agent to modify the repository.

43.2 Evaluation Harness

The harness compares two arms:

A. direct repository discovery by an agent
B. RepoCue-assisted repository discovery

The core harness is model-neutral. Optional external runners provide agent- or tokenizer-specific observations through a versioned JSON contract. Missing measurements are recorded as not_observed, never as zero.

Capture at least:

RepoCue baseline and update cost
agent token consumption where observable
cue bytes and estimated tokens
tokenizer-specific measured token counts when supplied
repository files and bytes read
Git, search, and tool-call counts where observable
task-ready latency
fallback repository reads after a cue
context correctness and completeness findings
reuse cost for 1, 2, 3, 5, and 10 consumers

The runtime fast path retains ceil(serialized UTF-8 bytes / 4) as its token estimate. Evaluation stores measured tokenizer counts separately and does not couple core packages to an AI model or tokenizer.

Evaluation should use small, medium, and larger real Git repositories when locally available. Repository probes are read-only. Optimization follows repeatable measurement and identified bottlenecks rather than microbenchmarks.

MCP, Tree-sitter, embeddings, LLM integration, checkpointing, pruning, retention-policy enforcement, and filesystem watching remain out of scope.

44. Real Agent A/B Validation Milestone

Core Evaluation & Hardening is accepted. The next milestone validates the central hypothesis with real Codex CLI observations while retaining the model-neutral external runner boundary.

The first adapter uses fresh ephemeral codex exec runs, JSONL event output, an explicit read-only sandbox, and a stable structured response schema. Direct and RepoCue-assisted arms use the same repository state, working directory, model, reasoning effort, benchmark prompt, sandbox, and output schema. The assisted arm receives the overview cue as initial context and may perform any repository reads needed to resolve incomplete or uncertain context.

The first benchmark evaluates repository-state comprehension. It records project purpose, branch, HEAD, dirty state, tracked and untracked changes, entry points, components, documentation, recent relevant changes, and remaining uncertainties.

Codex JSONL values are retained as observed measurements when present. Classified commands, explicit file reads, combined totals, and reuse totals are marked derived. Runtime cue token counts remain estimated. Missing values are not_observed, never zero.

The deterministic scorer verifies branch, HEAD, dirty state, tracked changes, and untracked paths against the coherent RepoCue basis. Semantic fields are preserved for a separate qualitative assessment and are not presented as deterministic truth.

Every pair records repository HEAD, RepoCue snapshot, Codex CLI version, model, reasoning effort, benchmark version, output schema version, and agent command observations. Repository state is checked before and after every agent run.

Reuse analysis projects 1, 2, 3, 5, and 10 consumers while separating baseline, incremental refresh, cue, and fallback discovery costs. The central hypothesis must not be declared validated until real observed agent measurements exist.

Tree-sitter, MCP, embeddings, RepoCue-internal LLM use, checkpointing, pruning, retention-policy enforcement, and filesystem watching remain out of scope.

ADR 0001: Structural Analysis Backend Boundary

Status: accepted for experiment; production backend not selected

Date: 2026-08-28

Context

RepoCue requires a narrow structural-analysis boundary before any parser is allowed into the production build. The default binary is currently CGo-free, statically buildable for Linux, and cross-buildable for Windows amd64. M2 must first determine whether structural facts reduce agent fallback work enough to justify backend and indexing cost.

The initial boundary needs only language, file or module identity, definitions, types, functions or methods, signatures, public symbols, imports, and likely entry points. Full AST persistence, call graphs, data flow, embeddings, and LLM summaries are outside this decision.

Options Considered

Official Tree-sitter Go Binding

github.com/tree-sitter/go-tree-sitter is the correctness and performance reference. Its source imports C and embeds the Tree-sitter C runtime. Grammar bindings also compile generated C sources. Making it mandatory would require CGO and platform C toolchains, changing the current distribution contract.

Reference: https://github.com/tree-sitter/go-tree-sitter

Pure-Go Tree-sitter-Compatible Runtime

github.com/odvcencio/gotreesitter describes a pure-Go runtime that loads Tree-sitter parse-table data. It is a candidate for a later measured spike, not an accepted dependency. Compatibility across required grammars, query support, malformed-input behavior, update cadence, memory, and performance must be compared with the official runtime.

Reference: https://github.com/odvcencio/gotreesitter

WASM Through a Pure-Go Runtime

A Tree-sitter runtime and grammars can be compiled to WASM and hosted by Wazero. Wazero is implemented in Go and does not require CGO, preserving cross-build properties. The approach adds module packaging, runtime startup, host-call, memory, provenance, and grammar-distribution costs. The pre-release github.com/malivvan/tree-sitter project demonstrates this design but is not selected as a dependency.

References:

• https://github.com/wazero/wazero
• https://github.com/malivvan/tree-sitter

No Structural Backend

RepoCue can retain deterministic Git, filesystem, document ranking, entry- point conventions, and recent-commit facts only. This preserves the smallest runtime and deployment surface. It remains a valid production outcome if M2 does not show enough per-agent value to amortize parsing and indexing.

Decision

No production structural backend is selected in M2. RepoCue keeps a narrow conceptual boundary and uses an external Bash structural oracle only for the experiment. The oracle is not linked into RepoCue, is not persisted in SQLite, and does not change go.mod.

The official binding remains the reference implementation. Pure-Go and WASM options remain candidates only after M2 demonstrates structural value.

Consequences

• The default CGo-free Linux and Windows build properties remain unchanged.
• M2 can compare basic, ranked, and structural information under the same token estimate without committing to parser architecture.
• Oracle accuracy is intentionally limited and must be recorded as an experiment limitation.
• A later backend decision requires observed fallback, token, latency, baseline, refresh, memory, database-size, and distribution measurements.
• Any persistent structural index requires a separate storage-lifecycle decision. It must be keyed by stable entity and content-digest identity, store backend and version provenance, and update only changed source files.

ADR: Quantitative Reporting From Maintained State

Scope

This decision defines the calibration and reporting boundaries in the canonical reporting plan. It does not authorize real-agent experiments or establish measured savings.

Date: 2026-09-07 Status: accepted Source Decisions: D1-D23 in docs/milestone-10a4f02.md

Context

Runtime maintenance metrics describe RepoCue work, not agent savings. An agent comparison requires separately produced, compatible direct/basic pairs and explicit repository, producer, cue, runner, and measurement provenance. Routine reports must not invoke an agent or silently renew that evidence.

Decision

Keep imported numeric calibration in immutable versioned JSON below the cache. SQLite schema 3 stores only its digest, path, identifier, local binding, and applicability metadata. A transaction verifies the expected current snapshot before publishing its reference. Read-only reports support schema 2 and 3 and never migrate, refresh, generate a cue, or persist their output.

Bind source evidence to the target checkout and local epoch/snapshot, not to coincidentally equal snapshot IDs in independent databases. Versioned evidence covers Git state, tracked state, and non-ignored untracked content, including symlink target text without following links. Incomplete evidence cannot bind. Core snapshots continue indexing tracked files only. Keep detailed source inventories, raw answers, prompts, absolute evaluated paths, and scoring expected/actual values outside calibration and SQLite.

An exact verified binding is a measured reference. A compatible different snapshot in the same epoch permits estimates with profile drift shown. Changed untracked content under the same snapshot, incompatible contracts, or a new epoch suppress projections. Quality scores remain dated source observations, not renewed assessments of subsequent snapshots.

Calculate differences and reuse costs per matched pair before taking medians and ranges. Future scenarios are estimates, never observed consumer use. Token subsets are not added twice. Execution duration includes full cue CLI cost and recorded epoch maintenance, with their measurement boundaries stated. Agent Git-command classifications, actual Git subprocesses, scan bytes, and file-size proxies are different units. Missing compatible observations suppress only the affected total. There is no cross-unit cost score or inferred I/O savings. Zero/unfavorable per-consumer differences have no finite break-even.

Historical state selection uses parsed observation times strictly before the cutoff, with snapshot sequence resolving ties. Activity and maintenance use metric-row recording times. Neither boundary proves SQLite publication time. Ambiguous legacy scan-duration/Git-count zeros remain unobserved; retain raw rows and report known/unknown coverage per dimension. Current DB size and live validation are current observations, not historical facts.

Consequences

Reports can operate without a model or tokenizer dependency and preserve the CGo-free distribution. Calibration acquisition remains an explicit external cost. Missing evidence reduces available projections instead of creating optimistic zeros. Raw evidence must be retained separately to reproduce or renew an import. Cache removal also removes its calibration copies.

Alternatives Considered

Routine agent execution would mix reporting with experiment cost. Persisting raw responses in SQLite would widen privacy exposure and storage ownership. Names-only evidence would miss same-path untracked changes. Treating cue count as consumers or builder duration as full CLI cost would change the measurement boundary. These alternatives do not satisfy the approved contract.

Verification Or Enforcement

Canonical M1 T1-T22 specify contract, real Git/SQLite/CLI, failure, concurrency, privacy, history, calculation, and distribution checks. Their observed results are recorded in the canonical plan, separately from this accepted decision.

ADR: Original task context and retained evidence

Scope

This decision defines task context delivery and local evaluation independently of repository-state calibration and paid-model authorization.

Date: 2026-10-08 Status: accepted Source Decisions: D25-D30 in docs/milestone-10a4f02.md

Context

Overviews identify state but do not deliver applicable instruction or procedure text. Small output cannot establish task readiness, correctness, or credit savings. Command classification cannot prove source provision or check success.

Decision

Use independent declaration, cue, benchmark, answer, runner, and result versions. Keep legacy versions, SQLite schema, and content-free snapshots. Implement deterministic selection in Go: null dimensions are global; lists use OR within dimensions and AND between them.

Pin tracked regular declaration and source files to full-file snapshot digests. Support whole files or inclusive one-based ranges. Preserve original UTF-8, line endings, and final newline. Reject linked components and escaping paths. Stream hashing while bounding retained text. Keep the quiet-repository assumption.

Assemble required primary/check sources and provenance before whole optional units. Mandatory overflow fails; optional omissions remain explicit. Cues declare coverage without enforcing instruction authority or permissions.

Separate prompt/tool provision, task correctness, verification execution, and independent semantic assessment. Capture actual stdin and supported completion, exit, and output evidence. Unknown fields prove nothing. Explanation assessment binds the exact answer, source basis, and policy.

Prepare without an agent by default. Explicit execution performs one ordered overview/task pair. Retain external attempts before launch and raw evidence on failure, malformed output, cancellation, and basis errors. Summaries launch no process and retain wrong answers.

Use complete compatible counters and dated credit/speed rates. Validate subset bounds, absence, and overflow. Calculate matched differences before descriptive aggregates. Suppress verdicts without pre-execution policy, successful tasks, complete required delivery, and required pair coverage.

Consequences

Authors maintain applicability and renew changed pins. Original context can cost more than summaries; budget failures expose missing mandatory material. External evidence requires owner retention. Local fixtures prove software behavior, not provider support, model compliance, account billing, or savings. Paid runs require separate settings, policy, rates, spending, and continuation authorization.

Alternatives considered

Whole-file-only delivery increases input. Contained symlinks need separate link/target identities. Summaries introduce model cost and uncertain fidelity. Shared legacy calibration mixes incompatible task outcomes. Success-only publication hides failures and favorable sample selection. These alternatives do not meet the accepted slice.

Verification or enforcement

Canonical M4 / T1-T8 cover contracts, real source integrity, budgeting, shipped CLI/runner paths, retained failures, regressions, distribution, and independent acceptance. Observed results belong in the canonical milestone.

ADR: Explicit provider prompt caching and retained measurement

Scope

This decision defines optional Claude Messages requests over original task context, independently of legacy calibration and task-runner contracts.

Date: 2026-10-09 Status: accepted Source Decisions: D26-D30 in docs/milestone-10a4f02.md

Context

Repository context can be reused across tasks, but a small cue alone does not establish a provider cache hit, lower cost, correct answers, or compliance. Provider usage categories and pricing differ from Codex credit accounting.

Decision

Keep the core local and deterministic. Add independent versioned benchmark, request, observation, answer, and evaluation contracts without changing SQLite or legacy schemas. Preparation runs actual refresh and task-cue commands and freezes source identities, provider settings, limits, rates, and request bytes.

Place original selected UTF-8 sources once in a stable user content block. Keep task, Git basis, freshness, budget, omissions, and warnings after its explicit cache boundary. Repository text does not acquire system authority. Include all preceding settings and output schema in reusable identity.

Freeze model-specific thinking and effort along with model, API version, TTL, system instructions, output schema and output bound. Sonnet 5.5 uses thinking.type=between_tools and output_config.effort=high for the existing text-only, tool-free contract. Preserve output_config.format. Other supported profiles omit the new fields and retain their exact wire bytes and reusable identities. Unknown profiles fail before HTTP. Unexpected thinking blocks fail answer validation without discarding complete compatible usage or its cost.

Use standard Go HTTP for one explicit bounded non-streaming Messages request. An exclusive attempt directory and start journal precede execution. Validate source bytes and repository basis before send and basis after send. Retain failed, incomplete, and interrupted attempts. Do not retry or follow redirects. Read the API credential only during explicit run and exclude it from evidence.

Normalize ordinary input, cache creation by lifetime, cache read, and output as disjoint nullable counters. Creation aggregate is not added to its parts. Estimate USD with exact decimal arithmetic and dated compatible supplied rates. Unknown usage suppresses dependent totals. Failed answer cost stays visible.

Reconstruct frozen requests and recompute raw observations in a read-only summary without subprocesses or network. Compare full matched cycles including initial writes and outputs. Savings verdicts require observed cache reuse, complete compatible costs, successful delivery, correctness, and bound independent compliance assessments. Discovery validates exact source/item sets; explanation also requires semantic assessment.

Consequences

Explicit run sends selected original repository text to the chosen provider. Source authors maintain pins. Evidence lives outside the evaluated checkout and needs owner retention. Local TLS fixtures establish software behavior, not provider cache support, actual hits, account billing, or real savings. Paid experiments require separately selected settings and spending authority. The default build remains CGo-free and adds no mandatory runtime dependency.

Alternatives considered

Automatic cache calls obscure spending and failure counts. Shared legacy schemas conflate different token categories and quality criteria. Summaries lose original-source fidelity. Success-only evidence hides unsuccessful cost. These alternatives do not satisfy the accepted measurement boundary.

Verification or enforcement

Real CLI integration exercises Git, SQLite, extraction, assembly, HTTP, retention, and summary with only the outer TLS server substituted. Contract, accounting, race, distribution, and documentation checks enforce local behavior. Real-provider observations and milestone evidence are recorded separately.