Skip to content

fix(skills): page a large skill body through skill_search read - #14895

Merged
bolichen97 merged 1 commit into
mainfrom
fix/skill-search-read-pages-large-skills
Oct 2, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/skill-search-read-pages-large-skills

Conversation

@pepmach

@pepmach pepmach commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An agent can read any skill its scope lists through skill_search, however large, and a read that returns nothing says exactly why.

skill_search indexes, catalogs and recommends a skill whose SKILL.md is larger than 99,000 bytes, and then skill_search(action='read', key=...) refuses to return that same body: the read verb has a 99,000-byte capacity and no way to read past it. The refusal is one sentence naming three unrelated causes -- "outside this scope, unreadable, or exceeds the 99,000-byte read capacity" -- with no byte count and no hint of which one tripped. In the field that sentence led an operator to conclude the skill was "bundled / not on disk" when the file was on disk, readable, and simply over the capacity.

Why it matters

The largest, most detailed skills are exactly the ones an agent needs verbatim rather than from memory, and they are the ones the read verb rejects. The agent's only recourse is to leave the tool and read the raw file, which is what the tool's scope and confinement exist to avoid, or to reconstruct the procedure from stale memory. The catch-all error compounds it: it steers the reader toward a missing-file diagnosis for what is a size problem, so time is lost on a phantom.

Not a goal

  • Raising or removing the 99,000-byte capacity. It is a context budget (a tool response is cut at 100,000 characters, tail first), kept as the per-call page size. The capacity was not revisited here, and PINNED_SKILL_BODIES_CAP on the required-skill pinning path -- the same number -- is not touched; the two values stay paired and would move together.
  • Paging for action='search' or action='list', whose offset/limit semantics (result offset, result count) are unchanged.
  • Paging in any other tool, or a general file-paging facility.
  • Reading a confined project skill past PROJECT_SKILL_BODY_CAP. That bound is the confinement of an attacker-controlled checkout and paging does not widen it.
  • The two other callers of the whole-or-None read, deliberately left as they are: the required-skill startup path, whose SkillContextCapacityError names both bounds and whose remedy (fewer or smaller always: true skills, a readable file) does not depend on which one tripped, and $key activation in resolve_dollar_skills, which skips a refused key by design so the message it decorates still renders. Classifying either changes startup and activation output, which is outside the read verb this PR fixes.
  • The search path's placeholder for a confined result whose body did not fit the shared search budget ("Body unavailable or over budget; retry skill_search with this exact skill key.", handlers/prompts.py, search branch). Deliberately left: it is a search-result convenience, not a read, and its remedy is the exact read this PR fixes, which now says which condition tripped. Classifying it would change search/list output, which is out of this goal.

What changed (motivation → approach → change)

Symptom: a registered, searchable skill of 119 KB is unreadable through its own tool, and the error does not say why.

Root cause, two halves. (1) SkillsLoader.read_scoped_skill holds an exact read to a 99,000-byte bound with no way to ask for part of a body, so a larger body is refused outright; the bound exists because sanitize_response truncates a tool response at MAX_RESPONSE_LEN (100,000) characters from the tail, which would silently drop a large body's closing instructions, and the loader's policy is to refuse rather than truncate. That policy is a recorded decision in _read_global_skill_text's docstring ("half a skill is not a smaller skill: it is a body whose instructions stop mid-sentence"), and this PR keeps it: a read that asks for no page is still refused whole (never silently truncated) and the refusal now names the size, the capacity and how to page; a page is the one sanctioned partial read, partial only because the caller asked for one, and it always says what remains and where the next page starts. The docstring records that contract in the same hunk. (2) Every refusal on the read chain collapses to None: a key the scope does not hold, a file the fenced reader declines, and a body over the bound all reach the MCP tool as an empty match list, so the tool can only print one sentence naming all three. The causes are already distinguishable one frame down (FileTooLargeError versus a None read in that reader; an out-of-scope key or a repo_scope mismatch in the exact-read chain), so no detection is added: a reason is threaded from those sites to where the tool renders the string.

Change:

  • SkillsLoader.read_scoped_skill_page(key, *, only, project_dir, offset, limit, capacity) is the read verb's face. offset/limit are LINES (0-based first line, most lines), the unit the built-in file reader and spawn_status already page in. With neither given, the body is delivered whole when it fits the capacity and refused with its size when it does not. With either given, as many whole lines from offset as fit the capacity (at most limit) are returned with the next offset. The capacity bounds one delivery, not the file: a global body over it is read again under the shared 50 MiB file safety cap (the bound every unbudgeted skill read already has) to learn its size and serve its pages. A confined project body keeps PROJECT_SKILL_BODY_CAP as the bound on the whole file, so that refusal names the project bound and offers no page. read_scoped_skill keeps its whole-or-None contract for the required-skill and $key activation paths.
  • The exact-read chain is classified rather than flattened: load_skill, _read_global_skill_text and _exact_read_while_building (the SkillsLoader method and the function it delegates to in src/kiro_crew/skill_runtime/search.py) take the refusal_reasons out-parameter _read_enumerated_skill_bytes already uses, and _read_exact_key turns them into one of three reasons (outside_scope, unreadable, over_capacity). Once the scope holds a key, no failure to deliver its bytes is ever reported as a missing key.
  • The pager never materializes a body line by line: the line count is a scan, the page start is a walk of newline positions, and only the page's lines are copied out, so a newline-dense body at the 50 MiB file safety cap costs the body plus the page, not one object per line (a line list for such a body measured over ten times the body).
  • Gateway POST /api/skills/-/discover (and the compatible GET) accepts optional offset/limit for a read plus an optional capacity request field that it clamps to SKILL_READ_CAPACITY (a caller can only SHRINK the page, never widen it); it returns a page block (line_offset, line_count, total_lines, total_bytes, next_offset) beside a paged body, and answers a refused read with HTTP 200, an empty match list and a refusal block naming the reason and the bound.
  • The MCP tool (src/kiro_crew/mcp_tools/skills.py) sizes the page for the WRAPPED response: build_tool_response cuts a tool result at MAX_RESPONSE_LEN characters from the tail, and the tool's own framing (header, page line, reference-data markers, the key repeated) sits around the page, so it renders that framing with an empty body and the widest numbers a page can carry, takes the length off the ceiling, and sends the remainder as the read's capacity. Without that, a page sized to the bare ceiling plus a long key would lose its last lines to the cut while the next offset already counted them as delivered.
  • The MCP tool forwards offset/limit exactly when its caller gave them, renders one message per reason (the over-capacity one naming the body's size, the capacity for this key and the two paging parameters), and puts a page's navigation line in the HEADER ahead of the body, where tail truncation cannot reach it. The descriptor documents the two parameters' read meaning. The tool's audit record (SEL log_tool_invocation metadata) of a refused read carries the refusal reason beside the match count.
  • The 99,000 literal is named SKILL_READ_CAPACITY with the mechanism it protects; its value is unchanged.

Owning spec docs/system-specs/modules/memory-skills-hooks.md and docs/architecture/mcp.md are updated in the same commit.

Backwards compatibility

Compatible: every call that works today keeps working. A read with no paging parameter of a body that fits returns byte-identical output; search/list keep their offset/limit semantics; the gateway's read response keeps matches/next_offset and adds page/refusal beside them, and its new capacity request field is optional and shrink-only (absent means the ceiling); read_scoped_skill keeps its signature and contract, and the readers' new refusal_reasons keyword is optional. An MCP tool talking to a gateway that predates the refusal block prints one explicit "no reason was reported" line instead of guessing a reason.

Tests

Red-first on origin/main @ cbe6d6a0de: test/test_skill_read_paging.py ran 15 failed / 2 passed before the change (python -m pytest test/test_skill_read_paging.py -n0). The two that passed are contract guards that must hold on both sides (a fitting body is returned whole without paging; read_scoped_skill keeps its fits-or-None contract). The two tests added for the local GPT lane's blockers were red on the first candidate head (a 90-segment key pushed a full page to 101,397 characters, past the 100,000 response cap; the pager's peak allocation on a 500,000-line body was 17 times the body) and are green now. Green after: 22 passed.

  • TestPagedRead::test_a_body_over_the_capacity_is_read_whole_across_pages -- a 119,000+-byte registered skill: the plain read is refused naming its size, the capacity and offset/limit; paging from offset=0 until the answer names no next offset yields at least two pages, each within the capacity, whose concatenation equals the file. Red on main: the catch-all string.
  • test_a_page_states_its_lines_and_bytes_against_the_whole, test_limit_bounds_the_page_in_lines, test_an_offset_past_the_end_is_an_empty_last_page_naming_the_count, test_a_read_without_paging_returns_a_fitting_body_whole -- the page header's line span, byte count and next offset; limit in lines; an offset past the end is an empty last page that names the line count (not an error); whole-mode output unchanged.
  • TestRefusalMessages -- one test per branch asserting its own message and the absence of the other two: an unknown key is outside the scope; a hardlinked SKILL.md (which the no-link reader refuses) is unreadable; an over-capacity body names size, cap and paging, on an LF fixture and on one written with CRLF endings (the size named is the delivered text's, never the file's on disk, which the CRLF fixture makes larger); a single line wider than the capacity is refused by line number. Red on main: every branch printed the same catch-all.
  • TestGatewayContract -- the tool forwards offset/limit only when given and always a capacity below the ceiling; a page of exactly the requested capacity under a 90-segment key still fits one response and loses no line (sanitize_response leaves it untouched); each gateway refusal block renders its own message; the route (GET and JSON POST) pages, diagnoses, answers an offset past the end with an empty page block carrying the line count, honours a smaller capacity and clamps a larger one to the ceiling.
  • TestLoaderContract -- the pager's peak allocation on a 500,000-line body stays under three times the body (tracemalloc) while the page and the count are right; read_scoped_skill unchanged; a confined project body over PROJECT_SKILL_BODY_CAP is refused with confined=True, the project bound and no size (never read past the bound), with the project granted natively and, in a sibling test, admitted by stub on a platform that cannot walk a project tree -- the Windows shape, forced on every platform; and a confined body under the project cap is paged at a caller's smaller capacity (10,000 bytes against a 20 KB body: page one with the next offset; the whole read refused with its size and the paging hint), while the bound refusal names the project cap whatever capacity was asked for.
  • test/test_skills_composition_contract.py (main's frozen SkillsLoader surface) registers the two members this PR adds (_read_exact_key, read_scoped_skill_page) and the three signatures refusal_reasons widens (_exact_read_while_building, _read_global_skill_text, load_skill); without the five rows both TestSurface tests are red on this PR's surface, with them the file runs 85 passed.
  • Existing tests adapted to the new seam, intent unchanged: test_installed_post_exact_read_long_keys_and_scope_errors stubs read_scoped_skill_page (the method the route now calls); test_regular_global_mapped_namespace_keeps_normal_reader accepts the reader's new refusal_reasons keyword.

Gates from the worktree: scripts/check_black_formatting.py and scripts/check_subprocess_encoding.py (both pass on the committed scope), isort, flake8, mypy (no issues in 1899 files), scripts/docs-lint.sh (all checks passed). scripts/local-gate.py: backend related set 36,841 passed, 35 failed, of which 34 fail identically on the unmodified base commit in a detached worktree (file explorer app, pipeline conductor skill contract, auto-improvement members -- none touch the changed modules) and 1 (test_mcp_gateway_adopted_daemon_repair.py::test_a_stale_survivor_is_repaired_end_to_end) passes when run alone; frontend related set 336 of 342 files passed, the 6 failing files fail identically on the unmodified base under the same symlinked node_modules (Vite denies the out-of-tree module path), and this diff touches no website/ file.

Manual verification

N/A -- unit coverage sufficient: the new tests drive the real loader on a temporary skills root through the MCP tool (unsigned path) and through the gateway route (signed path), so both transports of the read verb are exercised end to end. Rounds 5 and 6 (the rebases onto current main) are evidenced mechanically: the gates and the named test files listed under Review lanes ran serially on each rebased head; no local review lane ran on them, and the CI lanes judge the pushed head.

Screenshots / video

no-visual-delta

Why no screenshot: no user-visible frontend surface changes; the diff is loader, gateway route, MCP tool text and docs.

Related Issues

Fixes #14832

Pattern harvest

Rule candidate: review-prompt
Pattern: a refusal path that collapses distinct causes into one None/empty result forces the user-facing message to enumerate every cause with "or"; classify at the point that knows the cause and render one message per class.

Review lanes

One local round, one lane at a time, each pinned to the CI model (kirocrew--readonly, read-only):

  • GPT (gpt-5.6-sol) on the first candidate head: BLOCK, 2 blocking, 0 advisory. (1) Renderer framing sat outside the page budget, so a near-capacity page under a long key crossed MAX_RESPONSE_LEN and the tail cut dropped lines the next offset had counted -- fixed: the tool derives the read's capacity from its own framing and the gateway clamps a caller's capacity to the ceiling (test_a_page_sized_to_the_requested_capacity_fits_the_response_for_any_key, red on that head). (2) The pager split a body of up to 50 MiB into three full line lists -- fixed: whole reads refuse before any scan, the count is a scan and only the page's lines are copied (test_the_pager_copies_only_the_page_out_of_a_newline_dense_body, red on that head). Both fixes are in this single commit.
  • Opus (claude-opus-5) on the fixed head: PASS, no findings.
  • First Principles (claude-fable-5, hand-briefed from the base commit's contract with the workflow's three data files) on the fixed head: CONCERNS, 3 items, all answered in this commit: item 6 (the page block echoed a capacity nobody read) -- subtraction applied, the field is gone; item 5 (the gateway's shrink-only capacity request field was not declared) and item 8 (the audit record's refusal reason was not declared) -- both declared in What changed above. A second FP pass on the head carrying those answers: CONCERNS, 2 items, both answered in this commit: item 3 (a fourth refusal reason for an offset past the last line duplicated the renderer's empty-page line) -- subtraction applied, the reason, its field and its message branch are gone and a past-the-end offset is an empty last page naming the count; item 2 (the search path's "Body unavailable or over budget" placeholder is a sibling of the collapsed refusal) -- declared as deliberately left under Not a goal, since it is search output and its remedy is the exact read this PR fixes. A third FP pass on the head carrying those answers: CONCERNS, 2 items, answered here without a code change. Item 1 asked for the paging to be deleted because an agent could read a global skill by its path with its own file reader; rebutted with the counted callers its own clearing condition asks for: the managed native skill startup views (the kirocrew-skill-view-* templates written by acp/skill_projection.py) and the kirocrew-heartbeat template declare @kirocrew-core/skill_search (or @kirocrew-core) and no fs_read, so for those agents the read verb is the only way to a skill body at all, and the issue's field case is exactly a body such an agent could not reach; the paging is also the direction the issue asks for and the scope this PR was opened under. Item 2 named two siblings of the collapsed refusal outside the read verb (the required-skill startup error's wording and $key activation's silent skip); both are listed as deliberately left under Not a goal with the reason. A fourth FP pass on the same head with this description: PASS (it counted the callers itself: 6 of the 52 installed @kirocrew-core templates have no file reader; its two "rides along" notes, the audit record's reason and the named constant, are declared above).

The lanes judged the commit on its original base; before the push it was replayed onto fresh main (which carries the pid-reader ratchet heal) with an identity proof: identical per-file numstat (7 files), identical 1,035 +/- lines, byte-identical commit message. Gates re-run on the replayed head: 437 related tests passed, black/encoding ratchets, isort, flake8, mypy (1903 files), docs-lint, and push_guard.py --require-single-on-base SAFE.

Round 3 (head 8928c3f332 on main @ 2e09b10304): the first CI round on 02cd0f4dec was green on all six review lanes and red on two Windows shards. Backend Tests (Windows) (1) failed two of this PR's own tests, each on an assumption in the test, not on the code.

  • test/test_skill_read_paging.py:194 (test_an_over_capacity_body_names_size_cap_and_paging) measured the fixture with len(path.read_bytes()). On Windows the text-mode write_text in the fixture helper writes CRLF, so that figure counts one CR per line: 120,918 bytes on disk for the fixture's 1,835 lines against the 119,083 bytes the refusal names. The code has one source for that number: _page_skill_body (src/kiro_crew/skills.py:385) measures the UTF-8 size of the decoded body, whose newlines _decode_skill_text (src/kiro_crew/skills.py:825) has folded exactly as a text-mode read would; the page header's byte counts and total_bytes come from the same line. The capacity is a budget on what one response carries, so the delivered size is the one to name. The test now measures the delivered text and runs a second time on a fixture written in bytes with CRLF endings (_skill(..., newline="\r\n"), test/test_skill_read_paging.py:33), asserting the on-disk figure is not named; the docstring of _page_skill_body pins that every size it reports is the delivered body's.
  • test/test_skill_read_paging.py:471 (test_a_confined_body_is_never_read_past_the_project_bound) admitted the project by stubbing only the enumeration (_iter) where project_skill_traversal_supported() is false, which it is on Windows (no O_DIRECTORY, O_NOFOLLOW or dir_fd). load_skill re-checks the trust verdict on its own before it reaches the confined reader (src/kiro_crew/skills.py:4197, through _trusted_project_key and skill_trust.canonical_key, src/kiro_crew/skill_trust.py:130, which answers None on such a platform), so the confined reader -- the only place the project bound is enforced -- was never reached, and _read_exact_key (src/kiro_crew/skills.py:8083) classified a visible entry with no size_cap as unreadable. In production on Windows the real enumeration lists no project rows, so a project key is outside_scope; the unreadable outcome exists only under the partial stub. The stub now covers both gates (_admit_project_without_traversal, test/test_skill_read_paging.py:505), and a sibling test (test_the_confined_bound_holds_where_projects_cannot_be_walked, :486) forces project_skill_traversal_supported to false so the Windows shape runs on Linux and macOS as well.

Red-first evidence: a Linux probe carrying the two original assertions against the two Windows shapes (a CRLF fixture; project_skill_traversal_supported forced false with the enumeration-only stub) failed with the same two lines CI printed -- AssertionError: assert '120,918 bytes' in 'Error: skill large/procedure is 119,083 bytes; one read returns at most 98,664 bytes. ...' and AssertionError: assert 'unreadable' == 'over_capacity' -- and the changed file runs 21 passed after. Backend Tests (Windows) (4)'s test_diag_procs.py::test_a_read_refused_as_too_soon_does_not_restart_the_window ("0.8s apart is under the floor") is the known Windows timing flake tracked in #13997 and #14183 and is not touched by this PR. Gates on this head: black ratchet, isort, flake8, mypy (1,903 files), harness parity, comment-history, subprocess-encoding, sync-io-in-async, cwd-relative reads, testpaths coverage, builtin-skill scope, loop-bound locks, brand name, feature map, changelog and decisions history, focus cue, docs-lint; push_guard.py --require-single-on-base SAFE on 2e09b10304; the replay onto that base carries a diff identical to the one judged (7 files, 1,055 + / 43 -) and the same commit message plus one sentence per Windows fix.

Round 4 (head 0d308badd0 on main @ 2e09b10304): the Round 3 CI was green on every shard and lane; the GPT lane's one advisory finding on 8928c3f332 (src/kiro_crew/skills.py:8032, max_bytes=capacity on the confined read) is a real defect in this PR's own code and is fixed here. Verification: read_scoped_skill_page passed the caller's capacity as the first read's bound; for a confined entry load_skill clamps that bound to min(max_bytes, PROJECT_SKILL_BODY_CAP) (src/kiro_crew/skills.py:4226), so a 20 KB project skill read at capacity=10_000 was refused size_cap at 10,000 bytes, and the confined branch, which re-read nothing, answered SkillReadRefusal(over_capacity, capacity=10000, confined=True) -- the project-bound message, naming a 10,000-byte bound the body does not exceed and offering no page. The gateway takes capacity from any client, so the contract this PR adds reaches the branch; the shipped MCP tool's own capacity (about 98,000 bytes) never drops under the project cap, so it did not. Fix: a body refused at the capacity is read again under the bound the whole file has anyway -- the shared file safety cap for a global body, PROJECT_SKILL_BODY_CAP for a confined one -- and then paged at the capacity; a confined body is never read past the project cap, and a body over that cap is refused naming PROJECT_SKILL_BODY_CAP, not the caller's page size (read_scoped_skill_page, src/kiro_crew/skills.py:8033-8045; the spec paragraph in docs/system-specs/modules/memory-skills-hooks.md says the same). Pages stay the one sanctioned partial read: a whole read of that body at the smaller capacity is refused with its size and the paging hint (confined=False, since pages exist), and the default-capacity read still returns it whole. Red-first evidence on 8928c3f332: test_a_confined_body_under_the_project_bound_pages_at_a_smaller_capacity (test/test_skill_read_paging.py:509) failed with SkillReadRefusal(reason='over_capacity', capacity=10000, size_bytes=None, confined=True, line=None) where a page was due, and the widened bound helper (_assert_confined_read_stops_at_the_bound, :563) failed twice with assert 10000 == 24750; the file runs 22 passed after. Gates on this head: black ratchet, isort, flake8, mypy (1,903 files), harness parity, comment-history, subprocess-encoding, sync-io-in-async, cwd-relative reads, testpaths coverage, builtin-skill scope, loop-bound locks, brand name, feature map, changelog and decisions history, focus cue, docs-lint; test_skill_mapping_and_lazy_default.py 30 passed; push_guard.py --require-single-on-base SAFE on 2e09b10304; the commit message is Round 3's plus one sentence on this fix.

Round 5 (head 8c292979f2 on main @ ecdc59abf4): no new finding; this round brings the commit onto current main, which had moved 284 commits past 2e09b10304 and left the PR conflicting. One conflict, in src/kiro_crew/skills.py: #15093 moved the body of _exact_read_while_building into src/kiro_crew/skill_runtime/search.py and left the SkillsLoader method as a one-line delegation, while this PR had threaded refusal_reasons through that body. Resolution: main's move wins -- the body stays in skill_runtime/search.py and the method stays a delegation -- and the PR's refusal_reasons is forwarded through it: the moved function takes the same optional parameter (default None) and passes it to loader.load_skill, so a size-capped read during the first catalog walk still reports over_capacity (+4/-1 in search.py; taking main verbatim would have silently turned that case into outside_scope). The rebase also met test/test_skills_composition_contract.py, new on main with #15093, which freezes the loader's member names and signatures: its two TestSurface tests were red on this PR's surface (two new members, three signatures widened by refusal_reasons); the five rows are registered (+9/-5) and the file runs 85 passed. Commit count and message unchanged (byte-identical by git cat-file); per-file +/- lines identical to Round 4 apart from the four lines of the while-building thread that moved with the body and the two files above. Gates on this head: black ratchet, isort, flake8, mypy (1,996 files), docs-lint, comment-history, harness parity; test_skill_read_paging.py 22, test_skill_mapping_and_lazy_default.py 30 and the composition contract 85 passed serially; push_guard.py --require-single-on-base SAFE on ecdc59abf4. Evidence for this round is mechanical only: no local review lane ran on it (the host was under its memory hold line when the round started); the CI lanes judge the pushed head. main's own CI on this base, run 36809266120 on ecdc59abf4, is green on every shard. Reds on the three main runs before it, none this PR's, cited in case a shard repeats one here: Backend Tests (Windows) (2) failed test/test_native_skill_projection.py::test_a_lock_file_a_launcher_still_holds_is_never_swept and ::test_leftover_alias_lock_files_are_swept_only_when_provably_residue on 36798669577, 36804404043 and 36805671000, tracked as #15651; Backend Tests (3.12, 4) test/test_autonudge_refactor_contract.py::TestInstanceSeamsReachEveryInternalCaller::test_every_store_write_goes_through_write_state (file lock) is flake #15676, red on 36804404043 and green on 36805671000; Backend Tests (3.12, 8) test/test_members_dm_thread.py::TestMemberActivityRoute::test_unreadable_timestamps_are_skipped_not_sorted_as_garbage was red once on 36798669577 and green since; Round 4's Backend Tests (3.12, 2) lent-hop pair is flake #14742 and passes serially on this head. Coverage Gate and PR Readiness follow those shards.

Round 6 (head 428b33af34 on main @ 6b033ab03a): no new finding; this round brings the commit onto current main again, which had moved 61 commits past ecdc59abf4 and left the PR conflicting. One conflict, in test/test_skills_composition_contract.py: #15660 registered its new _readable_frontmatter member and signature in the frozen SkillsLoader surface, at the rows where this PR registers _read_exact_key and widens _read_global_skill_text. Both sides add at one spot, so both are kept: main's row stands and this PR's rows stand beside it (the file's diff against main is exactly this PR's five rows and two names, as in Round 5). Nothing else needed a hand: main's changes to src/kiro_crew/skills.py (#15660's _readable_frontmatter and the BOM-tolerant decode) and to both docs files merged cleanly beside this PR's lines. Commit count and message unchanged (byte-identical by git cat-file); the per-file +/- lines of the PR diff are identical on the old base and the new one (9 files). Gates on this head: black ratchet, isort, docs-lint; test_skill_read_paging.py 22, test_skill_mapping_and_lazy_default.py 30 and the composition contract 85 passed serially; push_guard.py --require-single-on-base SAFE on 6b033ab03a. flake8 and mypy each report one item, the same line: src/kiro_crew/vector_memory_runtime/lessons.py:1206 names _row_stem_tokens_for_scan without its module prefix (undefined name). This PR does not touch that file; the line is main's own at 6b033ab03a (#15517), so Backend Lint & Type Check is expected red on main and on this head alike until main carries the fix -- cited, not changed here. Evidence for this round is mechanical only: no local review lane ran on it (the host was under its memory hold line); the CI lanes judge the pushed head. main itself is red at the moment on things this PR does not touch, and the rebased head inherits them: main's latest completed run, 36822696805 on d5bdff64e0 (the run on 6b033ab03a is pending), fails Backend Lint & Type Check on the lessons.py:1206 line above, Backend Tests (3.12, 5) and (Windows) (5) on test/test_lesson_turn_injection.py::TestSelection (eight NameErrors on the same name) and Backend Tests (3.12, 6) and (Windows) (6) on test/test_vector_memory_composition_contract.py::TestOneBindingPerSharedName::test_every_shared_name_is_read_through_its_owner -- all from #15517 (600d4b9515), heal PR #15737 open; Backend Tests (3.12, 4) and (Windows) (4) fail three test/test_fold_catalogue.py tests (the catalogue and the projection registry disagree about the subagents fold) from #15078 (21477628d4), heal PR #15744 open; Coverage Gate and PR Readiness follow those jobs. None is changed here; the branch picks them up on its next rebase once they merge.

Round 7 (head 2fd19f5c86 on main @ bc80d8d8a2): no new finding and no code change; rebased onto bc80d8d8a2, 86 commits past 6b033ab03a. The round-6 reds were the base's own breakage (fold catalogue / lessons.py), healed on main at d8fa6a527e; this head sits on a base that carries the heal. The replay was clean: main touched one PR file, docs/system-specs/modules/memory-skills-hooks.md, and it merged without a conflict hunk. Commit count and message unchanged (byte-identical by git cat-file); the per-file +/- lines of the PR diff are identical on the old base and the new one (9 files). Gates on this head: mypy clean (mypy src/kiro_crew/, 2,026 files, no issues), which confirms the round-6 Backend Lint & Type Check red was the base's, not this PR's; black ratchet and isort clean; test_skill_read_paging.py 22, test_skill_mapping_and_lazy_default.py 30 and the composition contract 85 passed serially; push_guard.py --require-single-on-base SAFE on bc80d8d8a2. flake8 reports one item in a file this PR does not touch: src/kiro_crew/autonudge.py:1797 F811 (redefinition of unused probes), main's own line at bc80d8d8a2 (#12781, 0141ede260) -- cited, not changed here; the same step runs on main, so the tip's own run is expected to report it too. main's latest completed run, 36889843703 on 5d298cdfc4, is green on every job; the run on bc80d8d8a2 (36939193968) is still queued. Evidence for this round is mechanical only: no local review lane ran on it; the CI lanes judge the pushed head.

Round 8 (head 8d6e965628 on main @ fa37aa54fd): no new finding and no code change; rebased onto fa37aa54fd, 9 commits past bc80d8d8a2. It picks up #16032 (1001b70611), the fix for the src/kiro_crew/autonudge.py F811 that made Backend Lint & Type Check red on Round 7, so that job is expected green here. One conflict, with #15977 (3fb49451a7, each search's incomplete flag returned with its own result), in src/kiro_crew/dashboard/handlers/prompts.py: this PR adds the read branch's page block and its return directly above the search call, and #15977 changed that call from matches = skills.search_skills( to report = skills.search_skills_report(. Adjacent lines, independent intents, so both are kept: this PR's lines stand, then main's call (the file's +/- lines against main are exactly this PR's own hunks, as on the previous base). #15977's other changes -- src/kiro_crew/skills.py, src/kiro_crew/skill_runtime/search.py, src/kiro_crew/mcp_tools/skills.py, the composition contract and the spec -- merged cleanly beside this PR's lines, and this PR reads none of the attributes #15977 removed (search_incomplete, pending_keys). Commit count and message unchanged (byte-identical by git cat-file); the per-file +/- lines of the PR diff are identical on the old base and the new one (9 files). Gates on this head: mypy src/kiro_crew/ clean (2,026 files); flake8 on CI's paths clean (the Round 7 F811 is gone); isort, black ratchet and docs-lint clean; test_skill_read_paging.py 22, test_skill_mapping_and_lazy_default.py 30 and the composition contract 85 passed serially, plus main's test_mcp_core_coverage.py 175 (the file #15977 changed for the MCP tool this PR also edits); push_guard.py --require-single-on-base SAFE on fa37aa54fd. main's own run on fa37aa54fd (36948439351) is still queued. Evidence for this round is mechanical only: no local review lane ran on it; the CI lanes judge the pushed head. On Round 7's head the lanes read GPT and Opus no findings, First Principles PASS, UX and Security clean, Design CONCERNS with one WATCH item (read mode decided by the presence of offset/limit, which an older MCP tool always sent); that item is carried forward unchanged and gets its disposition once ruled.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

@pepmach
pepmach requested a review from a team as a code owner September 29, 2026 01:41
@pepmach
pepmach requested a review from kyleseaman September 29, 2026 01:41
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 29, 2026
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 8d6e96562831ce1b6d30131b04e68562da7a5db1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify the stateless per-page cost: each page re-reads and decodes the whole body (up to the 50 MiB cap), so a huge skill pays that per page.

[DESIGN-REVIEWED] 8d6e965

Description read

[DESCRIPTION-READ] 57ae4dc7e64cb64862a98206a716d4a4123639616a5437eb3d19d982eb6ee661

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

Premise-level review of 8d6e96562831ce1b6d30131b04e68562da7a5db1 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify the narrowed whole-read band: bodies between the framing-reduced capacity (~97.5 KB) and 99,000 bytes now refuse-and-page where one call once delivered them.

What this change ships

Inventory (10 items) — 9 justified

Intent: FIX — a skill the catalog lists but whose body exceeds one response is unreadable through skill_search, and the refusal names three causes without saying which; the removed hunk itself carries both halves of the defect.

  1. A body too large for one response is readable in whole-line pages via offset/limit — justified
  2. A refused read names which one of three reasons stopped it, with sizes and the paging hint — justified
  3. Gateway discover accepts offset/limit/capacity (shrink-only) and returns page/refusal blocks — justified
  4. A whole read's effective capacity shrinks by the tool's framing, so near-cap bodies now page — justified
  5. New loader method read_scoped_skill_page beside the unchanged whole-or-None read — justified
  6. The audit log now records the refusal reason on a refused read — rides along
  7. A page's navigation line leads the body, in the header — justified
  8. An offset past the end is an empty last page naming the count, not a refusal — justified
  9. A confined project body is never paged past PROJECT_SKILL_BODY_CAP — justified
  10. Both owning specs updated in the same commit — justified

Checks run: read_scoped_skill has exactly 2 other callers (skill_runtime/delivery.py:266, skill_runtime/search.py:312), both declared as deliberately deferred; grep for _page|_paginate|splitlines(keepends found only result-list pagers, no existing byte-budgeted body pager; the line-paging precedent (spawn.py offset/limit) and hooks.MAX_FILE_BYTES (50 MiB) both confirmed; read_scoped_skill_page has 2 consumers, SKILL_READ_CAPACITY 3.

[FIRST-PRINCIPLES-REVIEWED] 8d6e965

Description read

[DESCRIPTION-READ] 79e3ef445194a009401d04077f8f6dcd7a639b8175ff6abfa181b9c939f67d9d

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 8d6e96562831ce1b6d30131b04e68562da7a5db1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 8d6e965

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 8d6e96562831ce1b6d30131b04e68562da7a5db1: <one-sentence reason>

@pepmach
pepmach force-pushed the fix/skill-search-read-pages-large-skills branch from 4fdd101 to 02cd0f4 Compare September 29, 2026 01:47
@github-actions

github-actions Bot commented Sep 29, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review — ✅ no blocking findings

Reviewed 8d6e96562831ce1b6d30131b04e68562da7a5db1 — this comment is updated in place on each push.

Review details

No blocking issues; two advisory findings, both on how the new refusal path reports itself to the model.

FINDING — src/kiro_crew/mcp_tools/skills.py:388 — a body whose one line exceeds the per-read capacity terminates the advertised paging loop with no way past it: _page_skill_body returns SkillReadRefusal(..., line=start) on the first iteration when spent + size > capacity and taken is empty, and the rendered message ("line {refusal['line']} ... so no page can hold it.") carries neither a resumable offset nor the remaining line count, so an agent that reached offset=5 by following each answer's next page: offset= stops there and never receives lines 6..N → Fix: name the skip-ahead offset in that branch (refusal["line"] + 1, already carried on the refusal) so the documented loop can continue.

FINDING — src/kiro_crew/skills.py:5470 — a confined project key read while catalog_status(project_dir) == "building" is classified SKILL_READ_OUTSIDE_SCOPE (entry is None and reasons empty, because _exact_read_while_building deliberately withholds the project tier — "a project skill therefore waits for the walk"), which _refused_read renders as the positive assertion "outside this agent's scope: no skill here has it. Use a full key...", telling the agent its correct key does not exist and to go find another one, where the replaced text hedged across all three reasons → Fix: when entry is None and self.catalog_status(project_dir) == "building", classify and word the refusal as not-yet-conclusive instead of outside-scope.

[OPUS-REVIEWED] 8d6e965

Verdict parsed from the review's SHA-scoped output markers for commit 8d6e96562831ce1b6d30131b04e68562da7a5db1.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 8d6e96562831ce1b6d30131b04e68562da7a5db1: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 29, 2026
@pepmach
pepmach force-pushed the fix/skill-search-read-pages-large-skills branch from 02cd0f4 to 8928c3f Compare September 29, 2026 02:54
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision labels Sep 29, 2026
@pepmach
pepmach force-pushed the fix/skill-search-read-pages-large-skills branch from 8928c3f to 0d308ba Compare September 29, 2026 03:56
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 29, 2026
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 29, 2026
@pepmach
pepmach force-pushed the fix/skill-search-read-pages-large-skills branch from 0d308ba to 8c29297 Compare October 1, 2026 03:52
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention labels Oct 1, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) October 1, 2026 06:01
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 1, 2026
@pepmach
pepmach force-pushed the fix/skill-search-read-pages-large-skills branch from 8c29297 to 428b33a Compare October 1, 2026 07:52
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 1, 2026
@pepmach

pepmach commented Oct 1, 2026

Copy link
Copy Markdown
Contributor Author

CI note for head 428b33af34 (ci.yml run 36832859907): seven of the eight red jobs are main's own breakage at this PR's base, reaching this head through the merge ref; the eighth is a tracked flake. None of the failing files is in this PR's diff (skills.py, skill_runtime/search.py, mcp_tools/skills.py, their tests and two docs pages only).

Red job Failing Cause on main Fixed by
Backend Lint & Type Check (3.12) flake8 F821 src/kiro_crew/vector_memory_runtime/lessons.py:1206 (_row_stem_tokens_for_scan) the row-token helper moved behind text_scoring and lessons.py still named it bare #15744 (d8fa6a527e)
Backend Tests (3.12, 5) and (Windows) (5) test/test_lesson_turn_injection.py, 23 tests, NameError: _row_stem_tokens_for_scan same helper at runtime #15744
Backend Tests (3.12, 6) and (Windows) (6) test/test_vector_memory_composition_contract.py, 2 tests (one binding per shared name) same helper read outside its owner #15744
Backend Tests (3.12, 4) and (Windows) (4) test/test_fold_catalogue.py, 3 tests (subagents fold missing from the committed catalogue) catalogue not regenerated for the new fold #15744
Backend Tests (Windows) (8) test/test_members_dm_thread.py::TestResumeGuards::test_concurrent_member_resume_does_not_duplicate_history (history duplicated: 2 copies) open flake, tracked in #15650 —
Coverage Gate fails closed on the shards above consequence of the above clears with them

This run was created at 07:52:17Z, twenty-two seconds before #15744 merged as d8fa6a527e (07:52:39Z), so its merge ref predates the fix. Main's own run on d8fa6a527e (36832900240) passes Lint, the Windows 4/5/6 shards and the Coverage Gate, so the seven jobs clear on the next run of this head; Windows (8) is tracked in #15650 and is not this PR's.

@pepmach
pepmach force-pushed the fix/skill-search-read-pages-large-skills branch from 428b33a to 2fd19f5 Compare October 1, 2026 23:52
The exact read held a body to a 99,000-byte capacity with no way to ask
for part of it, so a registered skill larger than that was searchable
and recommended yet unreadable through its own tool, and every refusal
on the read chain collapsed to None, leaving one sentence that named
three causes without saying which one tripped.

The capacity stays as the per-call page size: a tool response is cut at
MAX_RESPONSE_LEN characters from the tail, so a body over it is refused
whole rather than truncated. The read verb now takes offset and limit in
lines, the unit the file and transcript readers already page in, and
delivers as many whole lines as fit the capacity with the next offset in
the header. A global body over the capacity is read again under the
shared file safety cap to learn its size and serve its pages; a confined
project body keeps PROJECT_SKILL_BODY_CAP as the bound on the whole file.
The read chain classifies each refusal as outside the scope, unreadable
or over the capacity, and the tool renders one message per reason, the
last naming the body's size, the capacity and the paging parameters.

The size a refusal names is the delivered text's, never the file's
on disk, and the test holds that under a CRLF checkout, the shape
a Windows text-mode write produces. A platform that cannot walk a
project tree admits the test project through both gates a read passes,
the enumeration and the trust verdict load_skill re-checks on its own,
so the confined bound is what the test measures there as well.

A confined body refused at a caller's smaller capacity is read again
under the project cap, the bound the file has anyway, so a body under
that cap pages at the capacity and a body over it is refused naming
the project bound, never the page size.
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 2, 2026
@pepmach
pepmach force-pushed the fix/skill-search-read-pages-large-skills branch from 2fd19f5 to 8d6e965 Compare October 2, 2026 01:52
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 2, 2026
@pepmach

pepmach commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

@pepmach

pepmach commented Oct 2, 2026

Copy link
Copy Markdown
Contributor Author

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Oct 2, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved: PR Readiness green on this head, merges cleanly into current main, no outstanding blocking review.

@bolichen97
bolichen97 merged commit 8b9132c into main Oct 2, 2026
102 of 103 checks passed
@bolichen97
bolichen97 deleted the fix/skill-search-read-pages-large-skills branch October 2, 2026 04:59
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

skill_search(action='read') cannot read a registered skill larger than 99,000 bytes, and its error is an ambiguous catch-all that hides the real cause

2 participants