From fec77026eaa4a3985aeeee8be5ddd3a59a479af7 Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Sat, 14 Nov 2026 14:10:53 +0000 Subject: [PATCH] docs(requirements): add 009 code graph, 010 security cache, 011 test cache MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Token-saving requirements picked by the operator on 2026-11-14: the code graph is initialised automatically per repository, security scan results are cached per file by content, and green test results are reused only under an exact key. Implementation follows once the running lanes land; the shared result store is requirement 003 of the quality repository. ๐ŸŽฏ Fix: 95 % ๐Ÿ’ฅ Break: 1 % ๐Ÿ’ธ Tokens: 100 % โฑ๏ธ Velocity: 100 % ๐Ÿ›ก๏ธ Security: 100 % ๐Ÿ† Score: 94 ๐Ÿšฆ Gate: โœ… 90/5, tokens and velocity <= 100, security 100 % Co-Authored-By: Claude Opus 5.5 --- .../requirements/009-code-graph-by-default.md | 216 ++++++++++++++++++ .../010-security-scan-cache-per-file.md | 172 ++++++++++++++ docs/requirements/011-test-result-cache.md | 147 ++++++++++++ docs/requirements/README.md | 3 + 4 files changed, 538 insertions(+) create mode 100644 docs/requirements/009-code-graph-by-default.md create mode 100644 docs/requirements/010-security-scan-cache-per-file.md create mode 100644 docs/requirements/011-test-result-cache.md diff --git a/docs/requirements/009-code-graph-by-default.md b/docs/requirements/009-code-graph-by-default.md new file mode 100644 index 0000000..90acf00 --- /dev/null +++ b/docs/requirements/009-code-graph-by-default.md @@ -0,0 +1,216 @@ +# 009 - Code Graph by Default + +## User Story + +As the operator running many agent sessions across repositories and +worktrees, I want every repository a session opens to carry a current +codebase-memory-mcp graph without any manual step, so that agents answer +structural questions from the graph instead of reading files and spend fewer +tokens. + +## Decisions (operator-confirmed 2026-11-14; do not re-litigate) + +1. **Depends on**: nothing. Independent of 010, 011 and quality 003. +2. **Timing**: implementation starts once the running agent lanes are done. +3. **Automatic per repository**: a session that opens a repository without a + graph indexes it itself, with no `index_repository` by hand and no + operator step; afterwards the graph stays fresh incrementally through the + watcher. Mechanism found in codebase-memory-mcp 0.12.1: both, with + separate jobs. The daemon's `auto_index` indexes and watches the MCP + session root when a session connects + (`application_background_initialize_impl` in `src/daemon/application.c`). + The SessionStart hook (`hook-augment`) only adds context: it never + indexes and never spawns a daemon (`src/main.c`). Measured 2026-11-14: + `_config.db` holds `auto_index = true`, so the skills `make install` did + switch it on (`scripts/install.sh`), yet `cbm-daemon.log` holds 1113 + `daemon.autoindex.skipped` lines for infinito-nexus-core and 8 for the + `feature-store-i18n` worktree, all `reason=unsafe_or_unavailable_path + files=-1`, and not one `autoindex.done`. `files=-1` means the bounded + admission count (5 s deadline, or an entry it cannot observe) failed, not + the file limit; the last graph was written 2026-11-12 22:24. +4. **Fix the refusal, no workaround**: the root cause of that admission + refusal is found and removed, in our repositories or upstream through an + issue. Rejected: raising `auto_index_limit` (the count fails, the limit is + not reached); an agent calling `index_repository` per session (a manual + step). +5. **Other repositories (proposed)**: the daemon auto-indexes only the + session root, so additional working directories and worktrees made during + a session stay unindexed. A skills `PreToolUse` hook resolves the git root + of each path a tool call touches; for a root without a graph it starts a + detached helper that holds one MCP connection, calls `index_repository` + with `async: true` and stays connected until the job succeeds, once per + root and session. A permanent daemon (`codebase-memory-mcp daemon start`, + run by a systemd user unit `kvb-code-graph.service` that `make install` + enables) keeps the watch after the helper leaves: upstream keeps a watch + past its last session only under `daemon start`, registers an async index + only while its session is connected, and a CLI index registers none + (README, Indexing and Session Coordination Daemon). Rejected: the hook + telling the agent to call `index_repository` (a manual step that costs a + turn); `codebase-memory-mcp cli index_repository` (no watch, so the graph + goes stale). +6. **Missing daemon, once per session**: upstream rate-limits its own notice + per cache folder to once in 900 s (`MAIN_HOOK_NOTICE_INTERVAL_SECONDS` in + `src/main.c`), not per session, so a second session within 15 minutes + hears nothing; `.hook-daemon-absent-notice` was last written 2026-11-14 + 12:21. The skills hook checks `codebase-memory-mcp daemon status` at the + first tool call of a session, after the MCP servers connected, and on a + missing daemon prints once per session id: + `codebase-memory-mcp: no daemon; run: systemctl --user enable --now + kvb-code-graph.service`. The same command becomes one `kvb-org-operator` + row. +7. **Worktrees get their own graph**: codebase-memory-mcp registers every + project under its absolute root, so each linked worktree is a separate + index (`docs/CONFIGURATION.md`, `ignore_worktrees`); one graph cannot + serve two checkouts. A worktree gets its graph through decision 3 or 5 and + loses it with decision 8. Rejected: `ignore_worktrees true` (a worktree + session would get no graph); seeding a worktree from a copied + `.codebase-memory/graph.db.zst` (README, Bootstrap: possible, but it needs + `persistence: true` writes into the main checkout after every index and a + copy step at worktree creation, for a saving not yet measured). +8. **Prune with the worktree**: removing a worktree deletes its graph in the + same step, inside the existing cleanup. `pkgmgr worktree cleanup` deletes + the project of each checkout it removes, and `pkgmgr gc`, the single + deterministic cleanup source picked 2026-11-14, lists every graph whose + root is gone or is no git repository as a low-risk candidate. Measured: of + the 10 graphs, 5 belong to removed skills worktrees + (`chore-requirement-001-audit`, `feature-workbench-w1` to `w4`, 174 MiB + together) and `/tmp/release-17.0.0` is no git repository. The pkgmgr part + is a package-manager task in the `kvb-org-rasci` register. Rejected: a + separate prune timer (a second cleanup source). +9. **Local only**: graphs are never committed; `.codebase-memory/` goes into + each repository's `.gitignore`, the "not shared" branch of + `kvb-agent-optimize`. Measured: skills, infinito-nexus-core, gui, + package-manager and quality ignore it nowhere today. +10. **Graph first, grep after**: skills and AGENTS.md keep sending code + questions to `search_graph`, `trace_path` and `get_architecture` first. +11. **Sandbox-proof checks (proposed)**: `codebase-memory-mcp config get + auto_index` fails inside the agent sandbox with "could not load saved + runtime settings", because `~/.cache/codebase-memory-mcp` lies outside + `allowWrite`; opening `_config.db` read-only works there. Checks read the + setting read-only or ask the daemon (`index_status`), never through + `config get` from the sandbox. + +## Approach + +```mermaid +flowchart TD + subgraph P["๐Ÿงญ 0 ยท Preparation"] + P1["๐Ÿ“‹ Write requirement"] --> P2{"โœ… Operator approves?"} + P2 -- "โœ๏ธ corrections" --> P1 + end + P2 -- "๐Ÿค– yes" --> A1 + subgraph A["๐Ÿ” A ยท Session root"] + A1["๐Ÿฉบ Find the admission refusal"] + A1 --> A2["๐Ÿ”ง Remove its cause"] + A2 --> A3{"๐Ÿงช Fresh clone indexed and reused?"} + A3 -- "๐Ÿ”ด no: fix" --> A1 + end + A3 -- "๐ŸŸข yes" --> B1 + subgraph B["๐Ÿช B ยท Other repositories and notice"] + B1["๐Ÿ—‚๏ธ Hook indexes other git roots"] + B1 --> B2["๐Ÿ“ข Daemon notice once per session"] + B2 --> B3{"๐Ÿงช Hook tests green?"} + B3 -- "๐Ÿ”ด no: fix" --> B1 + B3 -- "๐ŸŸข yes" --> BF{"๐Ÿ’ฌ Operator feedback?"} + BF -- "โœ๏ธ changes" --> B1 + end + BF -- "๐Ÿ‘ fits" --> C1 + subgraph C["๐Ÿงน C ยท Prune and ignore"] + C1["๐Ÿ—‘๏ธ Prune in pkgmgr cleanup and gc"] + C1 --> C2["๐Ÿ™ˆ Ignore .codebase-memory/"] + C2 --> C3{"๐Ÿงช Removed worktree leaves no graph?"} + C3 -- "๐Ÿ”ด no: fix" --> C1 + C3 -- "๐ŸŸข yes" --> CF{"๐Ÿ’ฌ Operator feedback?"} + CF -- "โœ๏ธ changes" --> C1 + end + CF -- "๐Ÿ‘ fits" --> D1["๐Ÿ Review, commit with operator OK, hand-over"] +``` + +## Acceptance Criteria + +### Session root + +- [ ] The commit that fixes the admission refusal names its root cause, and + a new session in infinito-nexus-core then writes `autoindex.done` for + it to `~/.cache/codebase-memory-mcp/logs/cbm-daemon.log`. +- [ ] Fresh clone: a session started in a new `git clone` of skills finds the + clone in `list_projects` with more than 0 nodes, with no + `index_repository` call in its transcript and no new operator row. +- [ ] Second session: a second session in the same clone adds no + `autoindex` line for it to `cbm-daemon.log`, `list_projects` still + holds exactly one entry for that root, and `index_status` reports + `watch.watched: true`. +- [ ] Fresh incrementally: after a commit that adds a function to the clone, + `search_graph` finds the function within one watcher poll, with no + `index_repository` call. + +### Other repositories + +- [ ] A session rooted in skills that reads a file of an unindexed + package-manager clone leaves that root in `list_projects`, and once the + helper has exited `index_status` reports `watch.watched: true` for it. +- [ ] `make install` enables `kvb-code-graph.service`, and after the last + agent session closes `codebase-memory-mcp daemon status` still reports + a running daemon. + +### Worktrees and pruning + +- [ ] A new linked worktree of skills gets its own entry in `list_projects` + from the first session or tool call in it. +- [ ] `pkgmgr worktree cleanup --apply --branch ` removes that worktree's + project: `list_projects` no longer lists it and its `.db` file under + `~/.cache/codebase-memory-mcp/` is gone. +- [ ] `pkgmgr gc --json` lists each graph whose root is missing or no git + repository as a low-risk candidate; on the state of 2026-11-14 it names + the 5 removed skills worktrees and `/tmp/release-17.0.0`. + +### Daemon notice + +- [ ] With no daemon running, the first tool call of a session prints the + notice with the exact command once, later tool calls of that session + print nothing, and a second session prints it once again. +- [ ] The command appears as one `kvb-org-operator` row, not one per session. +- [ ] With a daemon running, no notice is printed. + +### Local only and instructions + +- [ ] `git check-ignore -q .codebase-memory/graph.db.zst` exits 0 in the main + checkouts of skills, infinito-nexus-core, gui, package-manager and + quality. +- [ ] `kvb-agent-optimize/SKILL.md` step 2 names the daemon `auto_index` for + the session root and the hook for every other repository, and no longer + says `make install` alone indexes every repository a session opens. +- [ ] `agents.py` reports `auto_index` from inside the agent sandbox by + opening `_config.db` read-only. +- [ ] `AGENTS.md` of skills still sends code questions to the graph first and + to grep after. + +### Tests + +- **Unit** + - [ ] `test_hook_resolves_git_root`: a path in a subfolder, in a linked + worktree and in a submodule each resolves to its own root. + - [ ] `test_hook_indexes_once_per_root`: two tool calls on one unindexed + root start one helper. + - [ ] `test_hook_skips_indexed_root` and `test_hook_skips_non_git`: an + indexed root and a path outside git start nothing. + - [ ] `test_notice_once_per_session` and `test_notice_silent_with_daemon`. + - [ ] `test_auto_index_read_only`: `agents.py` reads `auto_index` from a + read-only `_config.db` fixture. + - [ ] `test_gc_lists_orphan_graphs` (package-manager): a graph of a missing + root and one of a non-git root are listed, a live root's is not. +- **Integration** + - [ ] `test_code_graph_fresh_clone`: the real binary, a temporary clone under + the real cache root (upstream refuses a different `CBM_CACHE_DIR` + while the live daemon runs): the first MCP session indexes, the second + reuses; the test deletes its project afterwards. + - [ ] `test_code_graph_helper_watch`: the hook's helper indexes an + additional root and the watch outlives the helper under `daemon + start`. + - [ ] `test_code_graph_worktree_prune`: a worktree's graph is gone after + `pkgmgr worktree cleanup --apply`. +- **E2E** + - [ ] `tests/e2e/test_code_graph_e2e.py`: a headless agent session in a fresh + clone answers one structural question through `search_graph` with no + `index_repository` call in its transcript, and a second session adds + no `autoindex` line for that root. diff --git a/docs/requirements/010-security-scan-cache-per-file.md b/docs/requirements/010-security-scan-cache-per-file.md new file mode 100644 index 0000000..29bad35 --- /dev/null +++ b/docs/requirements/010-security-scan-cache-per-file.md @@ -0,0 +1,172 @@ +# 010 - Security Scan Cache per File + +## User Story + +As an agent running `kvb-check-security` on many branches and sessions, I +want the MEDUSA findings of every unchanged file reused under an exact +per-file key, so that one changed file rescans only that file and the same +file is never scanned twice across branches and sessions. + +## Decisions (operator-confirmed 2026-11-14; do not re-litigate) + +1. **Depends on**: quality 003 (the result store). Independent of 009 and + 011. +2. **Timing**: implementation starts once the running agent lanes are done + and quality 003 has shipped its store. +3. **Today, measured**: `keyed()` in `scripts/security.py` hashes the script, + the medusa binary's path, mtime and size, `PATH`, the files not covered, + every `MEDUSA_*` variable and, per copied file, its tree path, repository + path, mode and content; one entry per whole diff lives in + `/security-cache/` for `CACHE_SECONDS` (24 h), and medusa + runs with `--no-cache`. One changed file therefore rescans the whole diff, + and an unchanged file on another branch or in another session is scanned + again; the ModelAttackScanner needs 71.8 s for one 2949-line file. +4. **Key per file**: the sha256 of the file content, the medusa version + (2026.7.0 today, from its dist-info), a digest of medusa's rule set (its + `rules/` tree and the RULES that `security.py` reads from medusa's + source) and the digest of `security.py`. No time expiry: the key changes + whenever anything relevant changes. Rejected: the whole-diff key (today's + behaviour); a 24 h expiry (a key that changes with every input needs + none). +5. **What selects and runs a scanner joins the key (proposed)**: medusa + picks scanners by extension, exact name, prefix and parent folder name + (`ai_context_scanner`, `rag_security_scanner`, `mcp_config_scanner` and + `agent_memory_scanner` read `file_path.parent.name`), and most scanners + call external tools found on `PATH` (shellcheck, semgrep, gitleaks, trivy + and more). The key therefore also holds the scanned tree path, the file + mode, every `MEDUSA_*` variable and the resolved path, size and mtime of + each external tool, as today's key holds `PATH`. Without them a moved file + or a newly installed tool would reuse findings it never produced. +6. **Cross-file check first**: before any per-file entry is written, prove + that medusa's findings for a file do not depend on other files of the + scan tree; where a cross-file rule exists, the files it reads stay per + diff. Found while drafting, medusa 2026.7.0: `trivy_scanner` runs `trivy + fs` on the file's parent folder, `rust_scanner` walks up to `Cargo.toml`, + `_find_config_file` in `scanners/base.py` walks up for tool + configuration past the scratch tree into `/tmp`, and + `docker_compose_scanner` runs in the file's folder. `medusa scan` has no + flag that selects scanners, so a file that `FILE_SCANNERS` routes to a + cross-file scanner stays in a per-diff group, keyed like today minus the + expiry. The check is an acceptance criterion. +7. **Through the quality store**: entries are written and read with + `quality store put` and `get` (quality 003) under tool `medusa`; + `/security-cache/` goes away. A payload holds per finding + only `rule`, `line` and `severity`, as quality decision 23 allows. `sha1` + and `context` are line hashes, which decision 23 keeps out of stored + data, so `security.py` recomputes them from the file after a hit; the file + content is part of the key, so they come out identical. +8. **Incomplete scans are never cached**: a run with a non-zero exit, a FAULT + or SKIP line, a `files_scanned` or `lines_scanned` shortfall, an + unreadable report or a file never covered writes no entry for any of its + files, as `scan()` does today. +9. **Accepted findings unchanged**: `security-accepted.jsonl`, `accept`, the + rule, path, sha1 and context match and the score formula stay as they + are. +10. **A store failure costs time only**: a missing quality binary or a store + miss on error runs medusa as today; it never yields a score without a + scan. +11. **Rejected: radio digest**. The operator rejected it on 2026-11-14: + every radio message stays in full in the hooks, because each one is sent + for a reason. + +## Approach + +```mermaid +flowchart TD + subgraph P["๐Ÿงญ 0 ยท Preparation"] + P1["๐Ÿ“‹ Write requirement"] --> P2{"โœ… Operator approves?"} + P2 -- "โœ๏ธ corrections" --> P1 + end + P2 -- "๐Ÿค– yes" --> A1 + subgraph A["๐Ÿ”ฌ A ยท Cross-file check"] + A1["๐Ÿงช Scan fixtures alone and together"] + A1 --> A2["๐Ÿ“‹ List cross-file routes"] + A2 --> AF{"๐Ÿ’ฌ Operator agrees with the list?"} + AF -- "โœ๏ธ changes" --> A1 + end + AF -- "๐Ÿ‘ fits" --> B0 + subgraph B["๐Ÿ—๏ธ B ยท Per-file key and store"] + B0{"๐Ÿ“ฆ quality 003 store shipped?"} + B0 -- "โณ no: wait" --> B0 + B0 -- "โœ… yes" --> B1["๐Ÿงฉ Key, payload, store calls"] + B1 --> B2{"๐Ÿงช Unit and integration green?"} + B2 -- "๐Ÿ”ด no: fix" --> B1 + B2 -- "๐ŸŸข yes" --> B3{"โฑ๏ธ Unchanged diff under 2 s?"} + B3 -- "๐Ÿ”ด no: fix" --> B1 + B3 -- "๐ŸŸข yes" --> BF{"๐Ÿ’ฌ Operator feedback?"} + BF -- "โœ๏ธ changes" --> B1 + end + BF -- "๐Ÿ‘ fits" --> D1["๐Ÿ Review, commit with operator OK, hand-over"] +``` + +## Acceptance Criteria + +### Cross-file check + +- [ ] `test_findings_file_local`: for a fixture set covering every + `FILE_SCANNERS` route, each file's findings scanned alone equal its + findings scanned inside the full fixture tree; every route where they + differ is listed in `CROSS_FILE` in `security.py`. +- [ ] `CROSS_FILE` holds the routes of `trivy_scanner`, `rust_scanner` and + `docker_compose_scanner` and the configuration names that + `_find_config_file` looks up, unless `test_findings_file_local` proves + one of them file-local. +- [ ] `test_cross_file_group_rescans`: changing a sibling of a file in the + per-diff group (a `Cargo.toml` next to a `.rs` file) rescans the group. + +### Key + +- [ ] `test_key_per_file`: with 10 scanned files of which 1 changed, medusa's + scratch tree holds that 1 file and the other 9 come from the store. +- [ ] `test_key_across_branches`: an unchanged file on a second branch, + scanned by a second process, hits without running medusa. +- [ ] `test_key_parts`: each of content, medusa version, rule set digest, + `security.py` digest, tree path, mode, a `MEDUSA_*` variable and an + external tool's mtime changes the key. +- [ ] `rg -n CACHE_SECONDS scripts/security.py` finds nothing. +- [ ] The medusa command line still carries `--no-cache`. + +### Store + +- [ ] `test_store_payload_fields`: every stored finding holds exactly `rule`, + `line` and `severity`. +- [ ] `test_hit_fingerprints_match`: `sha1` and `context` of a hit equal those + of a fresh scan of the same file. +- [ ] `test_no_legacy_cache_dir`: a scan writes nothing under + `/security-cache/`. +- [ ] `test_store_missing_runs_scan`: without the quality binary, or with a + store that errors, the scan runs and its output equals today's. + +### Incomplete scans and accepted findings + +- [ ] `test_incomplete_caches_nothing`: a FAULT line, a non-zero exit, a + `lines_scanned` shortfall, a SKIP line and an unreadable report each + leave zero store entries for every file of that run. +- [ ] The existing accepted-findings tests in `tests/test_security.py` pass + unchanged, and `test_hit_accepts_like_scan`: a hit with an accepted + finding leaves the score as a fresh scan does. +- [ ] `test_hit_output_identical`: output line, `--json` and exit code of a + hit equal those of a fresh scan of the same diff. + +### Speed and scope + +- [ ] A second `security.py` run over an unchanged diff holding the + 2949-line file that took 71.8 s finishes in under 2 s (`time`). +- [ ] The implementation's diff touches no file of `kvb-org-radio`. + +### Tests + +- **Unit** + - [ ] `test_key_parts`, `test_store_payload_fields` and the `CROSS_FILE` + routing of `taken()` results. +- **Integration** + - [ ] Real medusa on fixture trees with a temporary `XDG_CACHE_HOME`: + `test_findings_file_local`, `test_key_per_file`, + `test_key_across_branches`, `test_cross_file_group_rescans`, + `test_incomplete_caches_nothing`, `test_hit_fingerprints_match`. +- **E2E** + - [ ] `tests/e2e/test_security_cache_e2e.py`: two worktrees of skills on + branches sharing unchanged files; after the second `security.py` run, + `quality store stats --tool medusa` counts new rows only for the + files the second branch changed, and its score equals a run with the + store removed. diff --git a/docs/requirements/011-test-result-cache.md b/docs/requirements/011-test-result-cache.md new file mode 100644 index 0000000..654b6a5 --- /dev/null +++ b/docs/requirements/011-test-result-cache.md @@ -0,0 +1,147 @@ +# 011 - Test Result Cache + +## User Story + +As an agent proving 90/5 with `kvb-check-gate`, I want a target that already +ran green under the exact same inputs to be reused instead of rerun, so that +an identical tree never costs a second full `make test` while a gate still +never passes for a tree it did not run on. + +## Decisions (operator-confirmed 2026-11-14; do not re-litigate) + +1. **Depends on**: quality 003 (the result store). Independent of 009 and + 010. +2. **Timing**: implementation starts once the running agent lanes are done + and quality 003 has shipped its store. +3. **Today, measured**: `gate.py` records results per commit sha in + `kvb-gate.json` in the git common dir. Linked worktrees share that file, + but a new commit starts from zero even with an identical tree (an amended + message, a merge commit whose tree equals a gated one), and no clone sees + another clone's results. +4. **Green only, exact key**: only a GREEN result is reused, under an exact + key of the git tree hash of `HEAD`, the make target, a digest of the + lockfiles and toolchain versions and a digest of `custom.env`. A red + result always reruns and is never stored. +5. **The judge joins the key (proposed)**: the key also holds the digest of + `gate.py`, the sorted `--fail-regex` patterns, and the path and content + digest of every untracked, non-ignored file. A green under an older judge + or fewer fail patterns proves less, and `gate.py run` accepts untracked + files ("not part of the gate") although a test runner collects them. +6. **Lockfiles and toolchain**: lockfiles are the files named `uv.lock`, + `poetry.lock`, `Pipfile.lock`, `requirements*.txt`, `package-lock.json`, + `pnpm-lock.yaml`, `yarn.lock`, `Cargo.lock`, `go.sum`, `flake.lock`, + `Gemfile.lock` and `composer.lock` anywhere in the worktree, tracked or + not. The toolchain is the resolved path and first `--version` line of + `make`, `git`, `python3`, `node` and `docker` on the gate's `PATH`, a + missing one recorded as absent. Both lists live in one data constant. + Accepted limit: an image a test pulls by a mutable tag is outside the key; + such a project pins it in a lockfile or in `custom.env`. +7. **Hit output**: a hit prints `cached green from ` in the reason + column of the `run` line, with run = the origin commit's first 8 hex + digits and its log path, and date = its `finished` time; the entry is + recorded in `kvb-gate.json` for `HEAD` with `cached_from`, so `gate.py + status` shows it. +8. **No expiry**. Rejected: a 24 h expiry (an exact key needs none). +9. **Never pass a tree it did not run on**: a hit counts only when the origin + commit exists in this repository and its tree equals `HEAD`'s tree, the + tracked tree is clean, and `hotfix.py void` and `pending` decide as for a + run. A missing quality binary, a store error or a payload that fails + validation is a miss, never a hit. +10. **Rule text**: the `kvb-check-gate` rule "Only `gate.py run` on this head + marks a target green" gains one exception: a `gate.py run` on a commit + with the same exact key. A peer's report, CI and a dirty tree still never + count. +11. **Payload**: stored through `quality store put` under tool + `kvb-check-gate`, tool version the `gate.py` digest, rules digest the + fail-pattern digest and input digest the rest of the key; the payload + holds only `origin` (`commit`, `finished`, `path`) and an empty + `findings` list, as quality decision 23 allows. +12. **Accepted limit, measured**: core's `worktree-up` writes per-slot pins + into each worktree's `custom.env` (`scripts/system/worktree/up.sh`), so + with a whole-file digest no hit crosses core worktrees; core hits come + from identical trees in the same worktree. + +## Approach + +```mermaid +flowchart TD + subgraph P["๐Ÿงญ 0 ยท Preparation"] + P1["๐Ÿ“‹ Write requirement"] --> P2{"โœ… Operator approves?"} + P2 -- "โœ๏ธ corrections" --> P1 + end + P2 -- "๐Ÿค– yes" --> A0 + subgraph A["๐Ÿ—๏ธ A ยท Key and lookup"] + A0{"๐Ÿ“ฆ quality 003 store shipped?"} + A0 -- "โณ no: wait" --> A0 + A0 -- "โœ… yes" --> A1["๐Ÿงฉ Key from tree, target, locks, env"] + A1 --> A2["๐Ÿ”’ Origin tree and hotfix checks"] + A2 --> A3{"๐Ÿงช Unit and integration green?"} + A3 -- "๐Ÿ”ด no: fix" --> A1 + end + A3 -- "๐ŸŸข yes" --> B1 + subgraph B["๐Ÿšฆ B ยท Gate on a real repository"] + B1["๐Ÿ” Green, amend message, gate again"] + B1 --> B2{"๐Ÿงช Hit, and one changed byte reruns?"} + B2 -- "๐Ÿ”ด no: fix" --> A1 + B2 -- "๐ŸŸข yes" --> BF{"๐Ÿ’ฌ Operator feedback?"} + BF -- "โœ๏ธ changes" --> A1 + end + BF -- "๐Ÿ‘ fits" --> D1["๐Ÿ Review, commit with operator OK, hand-over"] +``` + +## Acceptance Criteria + +### Hit and miss + +- [ ] `test_cache_hit_same_tree`: target green on commit A, then commit B + with A's tree and another message: `gate.py run` does not start make, + prints `cached green from , `, and `status` shows + the target green with `cached_from`. +- [ ] `test_cache_red_never_stored`: a red run stores nothing, and the next + run starts make. +- [ ] `test_cache_key_parts`: each of the tree, the target, one lockfile byte, + one toolchain version line, one `custom.env` byte, the `gate.py` + digest, the fail-pattern set and an untracked file changes the key and + misses. +- [ ] `test_cache_no_expiry`: an entry whose `finished` lies 400 days back + hits. + +### Safety + +- [ ] `test_cache_origin_tree_check`: a payload whose origin commit is + missing locally, or whose tree differs from `HEAD`'s, is a miss. +- [ ] `test_cache_dirty_tree_exits_2`: dirty tracked files exit 2 before any + lookup, as today. +- [ ] `test_cache_hotfix_void`: with a voiding hotfix, `run` exits 3 and + records no hit. +- [ ] `test_cache_store_error_runs`: without the quality binary, or with a + store that errors, `run` starts make as today. +- [ ] `test_cache_never_cross_tree`: over 50 generated commit pairs with + distinct trees, no lookup hits. + +### Skill and script text + +- [ ] `kvb-check-gate/SKILL.md` names the exact-key hit as the only other way + to green, and keeps "a peer's report, CI, a dirty tree never". +- [ ] The `gate.py` docstring documents the key parts and the `cached green + from` reason. + +### Speed + +- [ ] On skills, after a green `make test`, `git commit --amend -m ` + followed by `gate.py run --target test` finishes in under 5 s. + +### Tests + +- **Unit** + - [ ] `test_cache_key_parts`, the lockfile finder and the toolchain probe + with a missing tool. +- **Integration** + - [ ] Temporary git repositories with a stub Makefile and a temporary + `XDG_CACHE_HOME`: `test_cache_hit_same_tree`, + `test_cache_red_never_stored`, `test_cache_origin_tree_check`, + `test_cache_hotfix_void`, `test_cache_store_error_runs`, + `test_cache_never_cross_tree`. +- **E2E** + - [ ] `tests/e2e/test_gate_cache_e2e.py`: on a skills worktree, `make test` + green, an amended message hits, and a one-byte change reruns make. diff --git a/docs/requirements/README.md b/docs/requirements/README.md index fe46054..aed83ac 100644 --- a/docs/requirements/README.md +++ b/docs/requirements/README.md @@ -12,3 +12,6 @@ skill defines the format. - [006 - Score Metric Overlays](006-score-metric-overlays.md) - [007 - Resources View](007-resources-view.md) - [008 - Home Dashboard](008-home-dashboard.md) +- [009 - Code Graph by Default](009-code-graph-by-default.md) +- [010 - Security Scan Cache per File](010-security-scan-cache-per-file.md) +- [011 - Test Result Cache](011-test-result-cache.md)