Repository navigation
fix(context): leave in-project links out of a declared steering glob - #19393
Conversation
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify that a KAS session gets a note about the left-out link: [DESIGN-REVIEWED] 2592bac Description read[DESCRIPTION-READ] b7648751e187dc30ebe8d86a7e9145339559b0c4da2a0e2ca6fe6aa0dcea16a2 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 |
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Check one thing before merge: is What this change shipsInventory (6 items) — 6 justifiedIntent: let a crew member whose template (or projected agent definition) declares the steering glob start when
[FIRST-PRINCIPLES-REVIEWED] 2592bac Description read[DESCRIPTION-READ] 039f5d3ba4de934653cd2d057f340eb9dabf0ec877149bb35349ed008be178d3 That sha256 names the PR description this verdict read. Recompute it with |
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
A crew member whose template declares the steering glob refused to start when that tree held a symbolic link, although the implicit steering scan of the same tree already leaves the link out and names it. A declared steering glob now leaves out, unread, a link whose target resolves inside the glob's root, and the snapshot names it in the existing linked-steering note. The KAS document reader does the same. A link that resolves outside the root or that the path screen refuses, a link under any other declared glob, and the launch-record size check keep refusing. Refs kirodotdev#18722
96a8dc8 to
2592bac
Compare
iamwhatever
left a comment
There was a problem hiding this comment.
This fixes the case where a crew member whose template, or an inheriting workspace's projected agent definition, declares a steering glob fails to start because the steering tree holds a symlink that stays inside the project. The root cause is that _resource_paths never handed _matches the linked collector that the implicit steering scan already passes, so the same link was harmless in one walk and fatal in the other. Now a pattern with a steering component passes the collector and confined=True. Such a link is left out unread and named in the existing linked-skipped note only when validate_file_path (which returns the fully resolved path) puts its target inside the admitted root. Any other link, and any link under a non-steering glob, still refuses. I tried to break it. A link whose target is outside the project, or one the screen cannot resolve (target None), still raises in _escapes. A link that is left out is never read or descended into, so the change can only drop content, never expose it. confined has no effect without a collector, so the launch-record measurers and the other callers behave exactly as before. A "steering" directory elsewhere in a declared glob gets the same skip-not-follow treatment, which is still the safe direction. The tests cover leaf, directory and literal-prefix links inside the project, outside-project links that still refuse, the projected and home-rooted globs, and the withheld launch record. The KAS reader dropping the note into a throwaway list (the Design punchline) costs only a diagnostic line, not correctness. Checks are green, base is main, it is mergeable, and both line-level lanes found nothing. — crew-pr-reviewer (deep re-check)
Problem / Motivation
Goal: A crew member whose template declares the steering glob starts when the project's steering tree holds a symbolic link that stays inside the project, as it already does when only the implicit steering scan reaches that tree.
A steering file kept elsewhere in the repository and linked into
.kiro/steeringis an ordinary setup. #17632 made the implicit steering scan leave such a link out and name it (member_essential_context.py:760and:778on e5a0b3d), and listed a template-declared glob that reaches the same link as out of scope. When a workspace inherits the default resources, the skill projection putsfile://.kiro/steering/**/*.mdand the global steering glob into each projected agent definition (acp/skill_projection.py:3214-3215), so the declared walk meets the same link._resource_pathscalls_matcheswith no collector (member_essential_context.py:927on e5a0b3d), the walk raises, and the member does not start:The projected globs also reach the KAS document reader,
projected_resource_documents(member_essential_context.py:1015on e5a0b3d).acp/runtime.py:7332calls it with no handler around the call, so the refusal propagates out of the session start.Why it matters
The same link is harmless in one walk and fatal in the other. #17632 only helps a member whose template does not declare the steering glob; a member that does declare it, as the projected views of an inheriting workspace do, cannot start while the tree holds the link.
Not a goal
validate_file_pathresolves inside the admitted root. Leaving that link out too is the implicit scan's rule and a one-condition change to this one (dropconfined); this change keeps the refusal that exists for it today.steeringcomponent, and a glob-free declared path that names a link. Both keep refusing;test_glob_leaf_link_cannot_silently_drop_a_declared_guideandtest_declared_literal_link_still_refusesare unchanged._declared_files_fitandprojected_launch_paths. They keep refusing a link: they count what kiro-cli loads, and a link cannot be counted without following it.What changed (motivation → approach → change)
Root cause: the link rule lives in the walk, which refuses a link unless the caller hands it a collector. The implicit steering scan hands one; the declared path to the same tree,
_resource_paths, never did.Change, all in
src/kiro_crew/member_essential_context.py:confinedis a new keyword of_matches(member_essential_context.py:385). Withlinkedandconfinedtogether, a link is left out only whenvalidate_file_pathresolves it inside the admitted root (_escapes,member_essential_context.py:427; used at the two link sites,member_essential_context.py:464andmember_essential_context.py:520). That is the screen the walk already uses, and it never probes a UNC target. Any other link refuses as before. The implicit scan passeslinkedalone, so it keeps leaving every link out wherever it points.linkedis a new keyword of_resource_paths(member_essential_context.py:917). For a pattern with asteeringcomponent, the test the snapshot already applies to a match, the collector andconfined=Truego to_matches(member_essential_context.py:950-951). Without a collector, or for any other pattern, nothing changes.documents_for_memberpasses itslinkedlist (member_essential_context.py:865), so the existingessential-context#linked-skippednote names the link.projected_resource_documentspasses a throwaway list (member_essential_context.py:1042) so the KAS session start is not stopped.docs/system-specs/modules/memory-skills-hooks.md:1701-1716replaces "A template that declares a glob reaching the same link still refuses" with the rule above.No new helper or module-level name:
confined,linkedand_escapeseach have a production reader named above, and the containment test is the one_readand the directory check in the same walk already apply.Links a declared steering glob meets, before and after:
.kiro/steeringitself (a literal prefix of the pattern), target inside the projectREADME.txtbeside*.md), target insidesteeringcomponent_declared_files_fit,projected_launch_pathsBackwards compatibility
Compatible: a session that refused at an in-project steering link now starts with one extra in-band note. A link was never loaded, so no loaded content changes, and every refusal other than "a steering glob meets a link that stays inside its root" is kept.
Removes nothing: no key, field, route or capability is removed or renamed. One test is renamed because its old name no longer describes it (see Tests).
Tests
In short: on main e5a0b3d the 13 new cases fail 3 of 3 runs with 6 failed, 7 passed; on this branch the changed file passes 3 of 3 runs with 258 passed, 2 skipped. Mutations: 6 of 6 fail only their own rule's cases.
New cases in
test/test_member_essential_context.py, by rule:test_declared_steering_glob_names_a_link_inside_the_project_instead_of_refusing,test_declared_steering_glob_names_a_linked_directory_inside_the_project_unread,test_declared_steering_glob_names_a_linked_steering_root_inside_the_project,test_declared_steering_glob_does_not_name_an_inside_link_it_would_never_readtest_projected_steering_glob_leaves_a_link_inside_the_project_out,test_projected_global_steering_glob_leaves_a_link_inside_home_outtest_declared_steering_glob_still_refuses_a_link_that_leaves_the_project(leaf, directory, dangling, unrelated name, linked steering root),test_projected_steering_glob_still_refuses_a_link_outside_the_projecttest_launch_record_stays_withheld_while_a_steering_glob_reaches_a_linkThe four snapshot cases build the real essentials envelope with the implicit scan opted out, so only the declared walk can meet the link; the two reader cases call
projected_resource_documentswith the projected globs, one rooted at the project and one at home.Red: the new test file copied onto main e5a0b3d, the 13 new cases, three runs, 6 failed and 7 passed each time, the same six names every time, every failure
MemberEssentialContextError: Essential source ...: linked document or directory. The six are the cases that need the link left out. The seven that pass on main pin refusals that stay (five escape shapes, the projected outside-link case, the launch-record case), so they are the guard against over-loosening.Mutations, one per rule, over the same file (baseline 25 passed for the cases selected by
-kon the branch): removing the containment test in_escapesfails only the six refusal cases; not passinglinkedfromdocuments_for_memberfails only the four snapshot cases; not passinglinkedfromprojected_resource_documentsfails only the two reader cases; dropping thesteeringtest in_resource_pathsfails only the unchangedtest_glob_leaf_link_cannot_silently_drop_a_declared_guide; letting_declared_file_bytespass a collector fails only the launch-record case; makingconfineddefault to true fails only the five existing implicit-scan cases.The old
test_declared_glob_still_refuses_a_linked_steering_fileis renamedtest_walk_without_a_collector_still_refuses_a_linked_steering_filewith the same body: it calls_matcheswith no collector, which still refuses, but a declared steering glob no longer always refuses.Neighbours: 22 files besides the changed one. Nineteen are the other test files that name
member_essential_context,documents_for_member,projected_resource_documents,projected_launch_paths,_declared_files_fit,kiro_launch_documents,native_context_documentsor_resource_paths; three more (test_hooks_composition_contract.py,test_lesson_turn_injection.py,test_skill_search_index.py) are whatscripts/run_scoped_tests.pyadds because they reference the edited spec. The three pass: 155 passed. The nineteen give 1229 passed and 18 failed: 17 intest/test_acp_spawn_offload.py::TestRuntimeProjectedLaunchDocumentsand 1 intest/test_native_skill_projection.py::test_launch_record_resources_match_the_alias_file_kiro_cli_loads. Those same 18 fail the same way on main e5a0b3d in a clean checkout:_ManagedEssentialSourceError, because pytest's base temp lies inside the crew data home on the machine that ran them, which the managed-state check refuses. This change does not touch them. The other gates also pass: black, isort, flake8 (including F821), mypy,check_subprocess_encoding,check_comment_history,check_brand_name,docs-lint, the harness-parity added-line gate andtest_flake_pattern_ratchet.py.Manual verification
N/A: unit coverage drives the real essentials builder and the KAS document reader with real symlinks on Linux. Windows junctions and macOS go through the same
is_link_or_junctionandvalidate_file_pathcalls but were not run on those platforms (unverified); the cases carryrequires_symlinks. There is no UI change.Related Issues
Refs #18722
_matches, so whichever lands second needs a rebase; the two are compatible, since a link that policy does not admit still has to be refused or left out.Pattern harvest
Not generalizable: the implicit and declared walks of one tree differing on a link is the split #17632 chose on purpose; this narrows it for the one tree both walk, and the other declared globs keep the old rule.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributed under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.