Skip to content

fix: skip a declared steering link that leaves the project - #30722

Merged
bolichen97 merged 1 commit into
mainfrom
fix/18722-outside-steering-link
Nov 6, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
fix/18722-outside-steering-link

Conversation

@bolichen97

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A crew member whose template declares a project steering glob starts when that steering tree holds a link to a file or folder outside the project, instead of failing before its first prompt.

A template that declares file://.kiro/steering/**/*.md (the shipped default, and the glob skill projection copies into agent definitions) walks the project's steering tree. When that tree holds a symbolic link whose target is outside the project, the walk raises and the member never starts:

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

The implicit steering scan meets the same link, leaves it out unread, names it in the essential-context#linked-skipped note, and the member starts. #19393 gave the declared glob that rule only for a link that stays inside the project.

Why it matters

Keeping shared steering in one folder and linking it into each project's .kiro/steering is an ordinary setup. Today such a member cannot start at all, and the same link is harmless when only the implicit scan reaches it. The KAS document reader (projected_resource_documents) refuses the same way, so a KAS session with the projected steering glob does not start either.

Not a goal

  • Reading anything outside the project. The link is left out unread and nothing under its target is opened or listed.
  • A link into managed memory or member state, or a target the path screen refuses (the crew data home, a sensitive path). Both keep refusing.
  • A link under a relative glob with no steering component, and a glob-free declared path that is a link. Both keep refusing.
  • Absolute declarations. fix(crew): leave out an absolute glob's link that leaves home #29319 already leaves out their outside links; nothing changes there.
  • The launch-record size check (_declared_files_fit, projected_launch_paths). It still cannot measure a link, so it keeps withholding the record.
  • Not naming a link the glob could never read (a README.txt beside *.md). An outside one is named in the note; nothing is read either way.

What changed (motivation → approach → change)

Symptom: a relative steering glob raises at a link that leaves the project. Cause: _resource_paths passes confined=True for a declared pattern, so _matches leaves out only a link that resolves inside the root, and it hands the outside leave-out (#29319) only to absolute declarations.

Change: for a relative steering glob, _resource_paths passes the same linked list as outside. A link that leaves the project then goes through the existing outside path in _matches: the target is screened with validate_file_path, _refuse_managed_source runs on it, and the link is left out unread and named in the linked-steering note the implicit scan already writes. One expression in src/kiro_crew/member_essential_context.py; the rest is docstrings.

Link a relative steering glob meets Before After
Target inside the project left out, named unchanged
Target outside the project (file, folder, dangling, the steering folder itself) refused left out unread, named
Target in managed memory/member state refused refused
Target the path screen refuses (crew data home, sensitive path) refused refused
Link under a relative non-steering glob refused refused

docs/system-specs/modules/memory-skills-hooks.md states the rule beside the absolute-declaration exception.

Backwards compatibility

Compatible: a member that starts today starts the same; only a member that refused at an outside steering link now starts, with that link named in the existing note. No loaded content changes, because the link was never read.

Removes nothing: the change turns one refusal into a named skip; no key, record, path or function is removed or tightened.

Tests

In test/test_member_essential_context_inherit_opt_out.py:

  • test_declared_steering_glob_names_a_link_that_leaves_the_project_unread (file, directory, dangling, unrelated name, linked steering root): the member snapshot builds, the outside body is not in it, and the note names the link. It replaces the test that pinned the refusal for these shapes.
  • test_projected_steering_glob_leaves_a_link_outside_the_project_out: the KAS reader returns the regular steering and not the outside body. It replaces the test that pinned the refusal.
  • test_declared_steering_glob_still_refuses_a_link_the_path_screen_refuses: a project steering link into another member's memory store under the crew data home still refuses.

Unchanged and still green: test_a_relative_glob_through_a_link_out_of_the_project_still_refuses (non-steering glob), test_a_link_out_of_home_into_an_admitted_managed_root_still_refuses (managed target), test_launch_record_stays_withheld_while_a_steering_glob_reaches_a_link. The module docstring of test/test_member_essential_context_outside_links.py now says a relative non-steering declaration keeps refusing.

Red/green: with the production change reverted, the two touched test files give 6 failed, 58 passed in 3 of 3 runs, every failure MemberEssentialContextError: ... linked document or directory; with it, 64 passed. Determinism: the three new or changed tests passed 20 of 20 at -n0, 10 of 10 at -n 4 --dist loadgroup --max-worker-restart=2 beside test_member_essential_context.py and test_member_essential_context_outside_links.py, and the two touched files passed shuffled (seed 24117). Related backend set (scripts/run_scoped_tests.py --surface backend): 1824 passed, 2 skipped.

Proof: not provable -- other: with the fix reverted the six new cases fail by raising MemberEssentialContextError in the call, which prove.py counts as an error rather than an assertion (INCONCLUSIVE); the manual red run above shows them red

Manual verification

N/A — unit coverage sufficient: the tests build real symbolic links on Linux and drive the real snapshot builder and KAS document reader. Windows junctions go through the same is_link_or_junction and validate_file_path calls but were not run here (unverified); the cases carry requires_symlinks.

Screenshots / video

N/A: no frontend change.

Related Issues

Closes #18722

Sibling sweep

Swept: git grep -n "linked document or directory" -- src/
Sibling: src/kiro_crew/member_essential_context.py:734 -- changed here

The two hits are the link sites in _matches (a literal path component at :734 and a wildcard one at :802); the one outside argument reaches both.

Pattern harvest

Not generalizable: the declared and implicit walks of one steering tree differing on a link is specific to the essential-context snapshot, and this closes the last gap between them for links that leave the project.

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

Contributions are accepted under the project's Apache-2.0 license.

@bolichen97
bolichen97 requested review from a team and KiroCrewCaptain as code owners November 5, 2026 19:40
@bolichen97
bolichen97 requested a review from CrysisDeu November 5, 2026 19:40
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 5, 2026
@bolichen97
bolichen97 enabled auto-merge (squash) November 5, 2026 19:43
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 0b4258fda6a3a7d501fcc00d99be6fc5c12206e3 — 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 does not.

First-Principles-Verdict: PASS

This is a one-expression fix for a refusal tracked in #18722. It sends the outside link through the existing outside path in _matches, so the same mechanism handles the cause.

What this change ships

Inventory (4 items) — 4 justified

Intent: let a crew member start when its project steering tree holds a link that points outside the project. FIX.

  1. A member whose relative steering glob meets a link leaving the project now starts. The link is left out unread and named in the linked-skipped note. — justified
  2. The KAS reader (projected_resource_documents) now skips that same link instead of refusing it, through the same _resource_paths expression. — justified
  3. The memory-skills-hooks spec states the new rule next to the absolute-declaration exception. — justified
  4. A link that the path screen refuses (another member's store under the data home) still refuses, and a new test pins it. — justified

[FIRST-PRINCIPLES-REVIEWED] 0b4258f

Description read

[DESCRIPTION-READ] cb792b5c94975161a1c74ee5ecb39d34eca738d19e2f5aaf8abbcdcee728f99d

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 Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 0b4258fda6a3a7d501fcc00d99be6fc5c12206e3 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: a relative steering glob now handles a link that leaves the project the way the implicit scan already does, through the existing screened outside path. Managed-state and screen-refused targets still refuse.

Notes

  • The old test that pinned the refusal was written as an interim step: fix(context): leave in-project links out of a declared steering glob #19393 named the outside-the-project case as the work still to do. Replacing that test closes a known gap and does not reverse a decision.
  • Windows junctions were not run (the description says "unverified"). If one misbehaves, the result is a refusal that a revert undoes, so it fails safe and does not block.

[DESIGN-REVIEWED] 0b4258f

Description read

[DESCRIPTION-READ] 48bd2749185c81220fd5e98d2fb11daacc8f0492a7d0e4c88d85b517795a72af

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 Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 0b4258fda6a3a7d501fcc00d99be6fc5c12206e3 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 0b4258fda6a3a7d501fcc00d99be6fc5c12206e3 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 0b4258f

Verdict parsed from the review's SHA-scoped output markers for commit 0b4258fda6a3a7d501fcc00d99be6fc5c12206e3.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 0b4258fda6a3a7d501fcc00d99be6fc5c12206e3 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 0b4258fda6a3a7d501fcc00d99be6fc5c12206e3 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 0b4258f

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 0b4258fda6a3a7d501fcc00d99be6fc5c12206e3 false-positive: <reason, 20 to 500 characters>

@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 Nov 5, 2026
@bolichen97
bolichen97 force-pushed the fix/18722-outside-steering-link branch from d84ea0b to 8e36c6a Compare November 5, 2026 23:16
@bolichen97

bolichen97 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in src/kiro_crew/acp/harness/kiro.py, src/kiro_crew/acp/session_mcp.py, src/kiro_crew/kiro_cli.py, src/kiro_crew/cli_doctor.py and several docs/system-specs/modules/ specs since this head went green (5e8741f -> 8c2e758); CI re-running. The patch is unchanged by the rebase.

The one red on the previous head, Backend Tests (3.12, 8), was test/test_push_guard_diagnostics.py::TestPushGuardChildren::test_the_child_dies_with_the_guard[SIGHUP] timing out on Linux (test_push_guard_diagnostics.py:1042, run https://github.com/kirodotdev/KiroCrew/actions/runs/42096154170/job/127490393558). This diff does not touch that test or the script it drives, and the node id passes 10 of 10 runs locally on the rebased head; Coverage Gate failed closed on that shard.

[operator: bolichen97]

@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 labels Nov 5, 2026
@bolichen97
bolichen97 force-pushed the fix/18722-outside-steering-link branch from 8e36c6a to 8c83937 Compare November 6, 2026 02:18
@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/memory-skills-hooks.md and several other docs/system-specs/modules/ specs since this head went green (8c2e758 -> 94579a2); CI re-running. The patch is unchanged by the rebase (same patch id), and the PR's targeted tests pass on the new base.

The one red on the previous head, Analyze (actions), failed while uploading its results, not in analysis; this PR changes no workflow file, and the re-run on the new head replaces it.

[operator: bolichen97]

@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 labels Nov 6, 2026
A crew member whose template declares a relative steering glob, such as
the shipped file://.kiro/steering/**/*.md, refused to start when that
tree held a link to a file or folder outside the project. The implicit
steering scan already leaves such a link out, unread, and names it.

The declared glob now does the same: the link is left out unread and
named in the linked-steering note, in the member snapshot and in the
KAS document reader. A link into managed memory or member state, and a
link the path screen refuses, still refuse, as does any link under a
relative glob without a steering component.
@bolichen97
bolichen97 force-pushed the fix/18722-outside-steering-link branch from 8c83937 to 0b4258f Compare November 6, 2026 05:19
@bolichen97

bolichen97 commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/ (same directory as the spec this PR edits) and in test/test_dashboard_server_composition_contract.py since this head ran CI (94579a2 -> 5c9a750); CI re-running. The previous head's two red backend shards failed on that contract test's lazy-import pin (131 vs 130), which main has since corrected; the patch is unchanged (same patch id).

[operator: bolichen97]

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 6, 2026
@github-actions github-actions Bot added the readiness: passed Eligible automated validation passed for the current revision label Nov 6, 2026

@KiroCrewCaptain KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Approved by Crew Captain for the on-call: checks green, PR Readiness passed, review lanes clean on this head.

@bolichen97
bolichen97 merged commit 477eebf into main Nov 6, 2026
98 checks passed
@bolichen97
bolichen97 deleted the fix/18722-outside-steering-link branch November 6, 2026 06:52
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 6, 2026
bolichen97 added a commit that referenced this pull request Nov 9, 2026
A crew member whose template declares a relative steering glob, such as
the shipped file://.kiro/steering/**/*.md, refused to start when that
tree held a link to a file or folder outside the project. The implicit
steering scan already leaves such a link out, unread, and names it.

The declared glob now does the same: the link is left out unread and
named in the linked-steering note, in the member snapshot and in the
KAS document reader. A link into managed memory or member state, and a
link the path screen refuses, still refuse, as does any link under a
relative glob without a steering component.

(cherry picked from commit 477eebf)

Backport note: release/0.12.0 splits the steering test into steering_glob and left_out in _resource_paths (#31131, #31152); the fix keeps those lines and changes only the relative-declaration fallback for outside= to left_out.
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.

A crew member still refuses to start when a declared steering glob reaches a symbolic link

2 participants