Skip to content

fix(context): leave in-project links out of a declared steering glob - #19393

Merged
javenciu merged 1 commit into
kirodotdev:mainfrom
javenciu:fix/declared-glob-linked-steering-18722
Oct 13, 2026
Merged

javenciu merged 1 commit into
kirodotdev:mainfrom
javenciu:fix/declared-glob-linked-steering-18722

Conversation

@javenciu

Copy link
Copy Markdown
Contributor

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/steering is an ordinary setup. #17632 made the implicit steering scan leave such a link out and name it (member_essential_context.py:760 and :778 on 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 puts file://.kiro/steering/**/*.md and the global steering glob into each projected agent definition (acp/skill_projection.py:3214-3215), so the declared walk meets the same link. _resource_paths calls _matches with no collector (member_essential_context.py:927 on e5a0b3d), the walk raises, and the member does not start:

MemberEssentialContextError: Essential source <project>/.kiro/steering/linked.md: linked document or directory

The projected globs also reach the KAS document reader, projected_resource_documents (member_essential_context.py:1015 on e5a0b3d). acp/runtime.py:7332 calls 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

  • A link whose target is outside the project root. It keeps refusing here: the walk leaves out only a link that validate_file_path resolves inside the admitted root. Leaving that link out too is the implicit scan's rule and a one-condition change to this one (drop confined); this change keeps the refusal that exists for it today.
  • A link under a declared glob with no steering component, and a glob-free declared path that names a link. Both keep refusing; test_glob_leaf_link_cannot_silently_drop_a_declared_guide and test_declared_literal_link_still_refuses are unchanged.
  • Reading a linked file's contents. That is the opt-in policy in fix: admit approved global steering symlinks #14007.
  • The launch-record measurers, _declared_files_fit and projected_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:

  • confined is a new keyword of _matches (member_essential_context.py:385). With linked and confined together, a link is left out only when validate_file_path resolves it inside the admitted root (_escapes, member_essential_context.py:427; used at the two link sites, member_essential_context.py:464 and member_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 passes linked alone, so it keeps leaving every link out wherever it points.
  • linked is a new keyword of _resource_paths (member_essential_context.py:917). For a pattern with a steering component, the test the snapshot already applies to a match, the collector and confined=True go to _matches (member_essential_context.py:950-951). Without a collector, or for any other pattern, nothing changes.
  • documents_for_member passes its linked list (member_essential_context.py:865), so the existing essential-context#linked-skipped note names the link. projected_resource_documents passes 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-1716 replaces "A template that declares a glob reaching the same link still refuses" with the rule above.

No new helper or module-level name: confined, linked and _escapes each have a production reader named above, and the containment test is the one _read and the directory check in the same walk already apply.

Links a declared steering glob meets, before and after:

Link Before After
Leaf file, target inside the project refused left out unread, named in the note
Directory, target inside the project refused left out, contents never listed, named
.kiro/steering itself (a literal prefix of the pattern), target inside the project refused left out, named
Link the glob could not use (README.txt beside *.md), target inside refused left out, not named (as in the implicit scan)
Any link whose target is outside the project, dangling or not, or that the path screen refuses refused refused
Link under a declared glob with no steering component refused refused
Glob-free declared path that names a link refused at read refused at read
_declared_files_fit, projected_launch_paths refuse refuse
Implicit steering scan, home and project leaves every link out unchanged

Backwards 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:

Rule Cases
A declared steering glob leaves an in-project link out and names it (a link the glob could not use is left out unnamed) 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_read
The KAS document reader leaves it out too test_projected_steering_glob_leaves_a_link_inside_the_project_out, test_projected_global_steering_glob_leaves_a_link_inside_home_out
A link that leaves the project still refuses test_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_project
The launch-record measurers keep refusing test_launch_record_stays_withheld_while_a_steering_glob_reaches_a_link

The 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_documents with 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 -k on the branch): removing the containment test in _escapes fails only the six refusal cases; not passing linked from documents_for_member fails only the four snapshot cases; not passing linked from projected_resource_documents fails only the two reader cases; dropping the steering test in _resource_paths fails only the unchanged test_glob_leaf_link_cannot_silently_drop_a_declared_guide; letting _declared_file_bytes pass a collector fails only the launch-record case; making confined default to true fails only the five existing implicit-scan cases.

The old test_declared_glob_still_refuses_a_linked_steering_file is renamed test_walk_without_a_collector_still_refuses_a_linked_steering_file with the same body: it calls _matches with 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_documents or _resource_paths; three more (test_hooks_composition_contract.py, test_lesson_turn_injection.py, test_skill_search_index.py) are what scripts/run_scoped_tests.py adds because they reference the edited spec. The three pass: 155 passed. The nineteen give 1229 passed and 18 failed: 17 in test/test_acp_spawn_offload.py::TestRuntimeProjectedLaunchDocuments and 1 in test/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 and test_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_junction and validate_file_path calls but were not run on those platforms (unverified); the cases carry requires_symlinks. There is no UI change.

Related Issues

Refs #18722

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

  • 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

Contributed under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.

@javenciu
javenciu requested review from a team and KiroCrewCaptain as code owners October 12, 2026 11:05
@javenciu
javenciu requested a review from dodgeblaster October 12, 2026 11:05
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 12, 2026
@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 2592bac1b7493f9976317c9b2e894cdc20d293f6 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify that a KAS session gets a note about the left-out link: projected_resource_documents drops it into a throwaway linked=[], so only the snapshot path reports it.

[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 .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 Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 2592bac1b7493f9976317c9b2e894cdc20d293f6 via the fork AI-review pipeline — 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

Check one thing before merge: is confined meant to keep two link rules? A declared steering glob still refuses an out-of-project link that the implicit scan leaves out.

What this change ships

Inventory (6 items) — 6 justified

Intent: let a crew member whose template (or projected agent definition) declares the steering glob start when .kiro/steering holds a symlink that stays inside the project. This is a FIX.

  1. A member with a declared steering glob now starts when the steering tree holds an in-project link, and the link is named in the linked-skipped note. — justified
  2. A KAS session start (projected_resource_documents) is no longer stopped by an in-project steering link. — justified
  3. Out-of-project links, links under non-steering globs, and literal link paths still refuse. — justified
  4. The spec sentence "A template that declares a glob reaching the same link still refuses" is replaced with the new rule. — justified
  5. The pin test_declared_glob_still_refuses_a_linked_steering_file is renamed and its docstring rewritten. The change is disclosed, and the reproduction plus 6 tests that fail on base show the old behaviour was wrong. — justified
  6. New keywords: confined on _matches (1 consumer), and linked on _resource_paths and _projected_resource_paths (2 consumers: documents_for_member and projected_resource_documents). — justified

[FIRST-PRINCIPLES-REVIEWED] 2592bac

Description read

[DESCRIPTION-READ] 039f5d3ba4de934653cd2d057f340eb9dabf0ec877149bb35349ed008be178d3

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 Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 2592bac1b7493f9976317c9b2e894cdc20d293f6 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 2592bac1b7493f9976317c9b2e894cdc20d293f6 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 2592bac

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 2592bac1b7493f9976317c9b2e894cdc20d293f6 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2592bac

@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 Oct 12, 2026
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
@javenciu
javenciu force-pushed the fix/declared-glob-linked-steering-18722 branch from 96a8dc8 to 2592bac Compare October 12, 2026 19:46
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention 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 labels Oct 12, 2026
@javenciu
javenciu enabled auto-merge (squash) October 13, 2026 00:49

@iamwhatever iamwhatever 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.

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)

@javenciu
javenciu merged commit 058faeb into kirodotdev:main Oct 13, 2026
149 of 152 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants