Skip to content

fix(context): skip a declared file:// resource that does not exist - #18278

Merged
buluoray merged 1 commit into
mainfrom
fix/skip-missing-declared-resource
Oct 9, 2026
Merged

buluoray merged 1 commit into
mainfrom
fix/skip-missing-declared-resource

Conversation

@buluoray

@buluoray buluoray commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A session whose agent template declares a file:// resource that does not exist starts normally, the way kiro-cli itself treats that template, instead of being refused.

Three reporters on 0.8.0.9 hit a refused session with Essential source .../AGENTS.md: missing, unreadable, or outside the admitted document root. One uses an AIM template (AmazonBuilderCoreAIAgents, Atlas) that declares file://AGENTS.md, and their workspace has no AGENTS.md. Another's subagent fails on .../subagent_<id>/README.md, because subagents start in an empty folder.

Why it matters

Every turn of an affected agent is refused, and nothing the user configured is wrong: kiro-cli loads the same template and skips the missing file. AIM-installed templates hit this out of the box, and subagents of any template that declares a project file hit it on every spawn.

Not a goal

  • Loosening the refusal for links (dangling or not), unreadable files, managed memory/member state, or paths outside the admitted root. All of those still refuse exactly as on main.
  • Changing how globs behave. A glob that matches nothing was already valid.
  • Changing Crew's own implicit AGENTS.md/SOUL.md scan (fix(members): read member sources on a home reached through a symlink #16263).

What changed (motivation → approach → change)

The essential-context reader refused the whole session when a declared literal file:// resource was simply absent. kiro-cli skips such a resource, so Crew refused sessions kiro-cli would have run.

The root cause is in member_essential_context.py. _matches returned root / pattern for a glob-free pattern without checking it exists, and _read turned the missing file into a session-wide refusal. A new probe, _is_absent, answers "absent" only when it lstats root-first, finds a missing component and meets no link on the way. A link, a managed-state path, an out-of-root path or a path whose lstat fails for any other reason is still handed to _read, which refuses it as before.

An absent declared resource is now skipped. The snapshot carries one essential-context#missing-skipped:<template> note naming the skipped files, like the existing #omitted, #managed-skipped and #linked-skipped notes, and the note is marked core so budget fitting cannot drop it. The KAS projection (projected_resource_documents) skips the absent file without a note, matching what KAS loads natively.

This reverses the rule #10586 recorded in docs/system-specs/modules/memory-skills-hooks.md ("A missing declared source still refuses"). That sentence is rewritten to describe the skip, the note and the cases that still refuse. #18269 is the evidence that the old rule refuses sessions kiro-cli runs.

Backwards compatibility

Compatible: a refusal becomes a skip only for a declared literal file that does not exist; every input main accepts loads the same documents, and nothing main refuses for a link, permission, managed-state or containment reason is admitted.

Reader: src/kiro_crew/context_assembly/member.py:documents_for_member -- chat|cron|subagent|crew page -- an absent declared file now yields a note instead of a raised MemberEssentialContextError; test_absent_declared_literal_resource_is_skipped_with_a_note
Reader: src/kiro_crew/acp/runtime.py:projected_resource_documents -- subagent|chat -- an absent file adds no projected document; test_projected_resources_skip_an_absent_file_in_an_empty_cwd
Reader: src/kiro_crew/acp/harness/kiro.py:kiro_launch_documents -- chat|subagent -- reads through documents_for_member, and its native_only read carries no note; asserted in test_absent_declared_literal_resource_is_skipped_with_a_note

Tests

In test/test_member_essential_context.py:

  • test_absent_declared_literal_resource_is_skipped_with_a_note: missing AGENTS.md and nested notes/README.md → the session builds, one note names both files, the note is core, and native_only carries no note.
  • test_present_declared_resources_add_no_missing_note: no note when nothing is missing.
  • test_projected_resources_skip_an_absent_file_in_an_empty_cwd: the subagent case through the KAS projection.
  • Still refused: test_declared_literal_link_still_refuses (dangling leaf, leaf linking outside, dangling parent directory), test_declared_literal_outside_the_root_still_refuses_when_absent, test_declared_literal_unreadable_file_still_refuses, test_declared_literal_under_an_unsearchable_directory_still_refuses, test_absent_managed_literal_resource_still_refuses.

Two existing tests used deletion to mean "refused source" and now use a present non-regular source (a directory): test_unreadable_declared_source_still_refuses_on_warm_hit in test/test_essential_delivery.py and test_a_refused_declared_source_still_refuses_when_the_envelope_is_over_budget. test/link_screen_sites.py records _is_absent as a link-refusing site; it never traverses a link, so it needs no hold.

Mutation checks:

  • With the skip removed, the two skip tests fail.
  • With the link check dropped from _is_absent, the dangling-parent case fails.
  • With the managed check dropped, the managed test fails.
  • When a permission error counts as absent, the unsearchable-directory test fails.

Manual verification

N/A — unit coverage sufficient: the change is confined to one pure reader, and the tests drive the same build_message path the refused sessions took.

Related Issues

Closes #18269

Pattern harvest

Rule candidate: review-prompt
Pattern: a glob-free "pattern" branch returns a path unconditionally while the glob branch treats no-match as valid, so a missing literal escalates into a hard failure.

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

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners October 8, 2026 23:39
@buluoray
buluoray requested a review from dodgeblaster October 8, 2026 23:39
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 8, 2026
@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision bbe82888efeae36f905d6a95a1fbe79df17345d5 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 8, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

A maintainer should confirm this PR may reverse #10586's recorded rule that "a missing declared source still refuses", and the two tests that pinned it.

[DESIGN-REVIEWED] bbe8288

Description read

[DESCRIPTION-READ] 87a31c24dc31dd5aaf8a816dbe340ed831596eda8b65bfab7bc207685575bfe0

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 8, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] bbe8288

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

@github-actions

github-actions Bot commented Oct 8, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of bbe82888efeae36f905d6a95a1fbe79df17345d5 — 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: CONCERNS

The skip is the fix. The added "DECLARED RESOURCES NOT FOUND" core note goes beyond the kiro-cli parity the Goal asks for, and its only support is symmetry.

Not justified as shipped

  • Item 2 — inherited: the Goal is to start "the way kiro-cli itself treats that template", and kiro-cli skips silently. The KAS projection in this same diff also "skips the absent file without a note, matching what KAS loads natively". The note's only support is "like the existing #omitted, #managed-skipped and #linked-skipped notes". No harm is named for an agent that is not told.
    Subtraction: delete _missing_declared_note, ESSENTIAL_MISSING_SKIP_SOURCE and the missing list in documents_for_member, and skip silently as the projection does.
    Clears when: a report shows an agent going wrong without the note, or the note is removed.
  • Item 4 — one consumer, generalized: _matches(..., missing: list[Path] | None = None) takes a literal pattern only from _resource_paths, which always passes a list (absent = [] if missing is None else missing). I grepped for _matches( and found 4 callers. The other 3 (lines 750, 768, 975) pass **/*.md globs, so the missing is not None branch can never run.
    Subtraction: make missing a required list on _matches, or drop the None guard.
    Clears when: the guard is removed, or a caller that passes a literal pattern with None is counted.

What this change ships

Inventory (5 items) — 3 justified

Intent: let a session whose template declares a missing file:// resource start, as kiro-cli does. FIX.

  1. A session (or subagent) with an absent literal declared file now starts instead of being refused — justified
  2. The snapshot carries a core "declared resources not found" note naming the skipped files — inherited (symmetry with the sibling notes)
  3. The spec rule "A missing declared source still refuses" is rewritten to describe the skip (the reversal is evidenced by Session refused when an agent template declares a file:// resource that does not exist #18269) — justified
  4. An optional missing parameter on _matches — one consumer, generalized
  5. Two refusal tests now use a directory instead of a deleted file — justified

[FIRST-PRINCIPLES-REVIEWED] bbe8288

Description read

[DESCRIPTION-READ] 16819bc3a25360e5f495219380b6962d6e6832bb13367c5f85b2c7202debaa68

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 8, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] bbe8288

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable bbe82888efeae36f905d6a95a1fbe79df17345d5: <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 Oct 8, 2026
@buluoray
buluoray force-pushed the fix/skip-missing-declared-resource branch from 4922fa9 to bbe8288 Compare October 9, 2026 00:00
@buluoray

buluoray commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=30ff0a9c6ebf A recorded decision is reversed as if it were a test-fixture detail — fixed in bbe8288

Fixed: docs/system-specs/modules/memory-skills-hooks.md no longer says a missing declared source refuses. It now states that an absent declared literal is skipped with a core #missing-skipped note, that the KAS projection skips it without a note, and that links, unreadable or non-regular files, managed paths and out-of-root paths still refuse.
The reversal of the #10586 rule is stated in the PR body. #18269 (three reporters, AIM templates and subagents) is the evidence the old rule refused sessions kiro-cli runs.
The maintainer acknowledgement this item also asks for is a human step and is requested in the hand-back, not claimed here.

@buluoray

buluoray commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=cbe3997f2b7b Item 5 — stale spec sentence — fixed in bbe8288

Fixed: the sentence "A missing declared source still refuses" in docs/system-specs/modules/memory-skills-hooks.md is replaced in this commit by a description of the skip and of the cases that still refuse.

@buluoray

buluoray commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=6eb9ef366480 Item 2 — the missing-skipped note is symmetry, kiro-cli skips silently — rebutted

Rebutted: the snapshot is the authoritative source list, and it says it replaces all prior sources. Without the note, an agent whose template names a guide cannot tell a deliberately empty template from an expected guide that never arrived. The #omitted note for a refused implicit guide exists for the same reason, so this is the same purpose, not copied shape.
The note is one line, carries no file content and is left out of the native_only read and the KAS projection, so it never changes what the host loads natively.
The issue's requested design asked for this note explicitly; removing it is a product call for a maintainer, not a correctness defect.

@buluoray

buluoray commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor Author
  • span=b5422cfac5df owning spec still says a missing declared source refuses — fixed in bbe8288

Fixed: docs/system-specs/modules/memory-skills-hooks.md now describes the skip-with-note behaviour for an absent declared literal and lists the cases that still refuse.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=38868d7c0a22 Item 2 — the missing-skipped note is symmetry, kiro-cli skips silently — rebutted

Rebutted: the essential snapshot declares itself the complete source list and tells the agent to stop applying sources absent from it. Without the note, an agent whose template names a guide cannot tell an empty template from an expected guide that never arrived. That is the reason the #omitted note exists for a refused implicit guide: same purpose, not copied shape.
The note is one line, carries no file content, and stays out of the native_only read and the KAS projection, so what the host loads natively is unchanged.
Removing it is a product preference the linked issue's design settled in favour of the note, not a defect; a maintainer can overrule it.

@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author
  • span=4a4781473c1e Item 4 — the optional missing parameter has one consumer — rebutted

Rebutted: missing=None is the fail-closed default, not dead generality. A caller that does not opt in keeps main's behaviour, where an absent literal reaches _read and refuses. Making the list mandatory would turn every future literal-pattern caller into a silent skipper by default.
It follows the two optional out-parameters already in the same signature, skipped and linked, which use the same opt-in shape for the same reason.

@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 9, 2026
@buluoray

buluoray commented Oct 9, 2026

Copy link
Copy Markdown
Contributor Author

Maintainer decision: I'm overriding the #10586 rule that a declared-but-missing essential resource refuses the session.

Rationale: three independent reporters on 0.8.0.9 (custom AIM agent templates declaring file://AGENTS.md, and subagents starting in an empty subagent_<id>/ folder) had sessions refused that kiro-cli itself starts fine, since kiro-cli skips missing declared resources. A plain missing file now admits the session with an omission note in context; symlinks, unreadable files, and paths outside the admitted root are still refused, so the boundary #10586 protected is unchanged.

Keeping the omission note (First Principles CONCERN rebutted): without it the agent can't tell an intentionally empty template from a resource that failed to arrive.

Reviewed at head bbe8288.

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

Approving at bbe8288. Read the full diff plus the owning spec; nothing blocking. Non-blocking notes, worth a follow-up or a quick fix before merge:

  • [MINOR] src/kiro_crew/member_essential_context.py:901 (_resource_paths) vs :393-416 (_matches) -- the same optional missing parameter has opposite defaults in two adjacent functions. _matches(missing=None) keeps main's behaviour (absent literal reaches _read and refuses), which is the fail-closed default the author's rebuttal to the First Principles lane relies on; but _resource_paths(missing=None) substitutes a throwaway list (absent = [] if missing is None else missing) and SKIPS silently. That is how projected_resource_documents (:857, passes no missing) gets the intended no-note skip, so the behaviour is deliberate, but the rebuttal ("a caller that does not opt in keeps main's behaviour") is only true one level down. Either have projected_resource_documents pass its own list explicitly and let _resource_paths forward missing unchanged (so None means "refuse" everywhere), or say in _resource_paths' docstring that None here means "skip without recording". Clarity only; no security effect either way since skipping reads nothing.
  • [NIT] src/kiro_crew/member_essential_context.py:352 (_is_absent) -- if not path.is_relative_to(admitted_root): return False is unreachable from the only caller: _matches already raises on absolute patterns and .. components (:334-337) and builds path = admitted_root / pattern. Harmless belt-and-braces; a one-word "defensive" in the docstring avoids a reader hunting for the case that reaches it.
  • [NIT] test/test_member_essential_context.py test_absent_managed_literal_resource_still_refuses -- writes under config_dir() / "workspace"; relies on the suite's KIROCREW_HOME isolation rather than tmp_path. Consistent with existing tests in the file, but worth keeping in mind per testing-conventions (host-state tests).

@buluoray
buluoray enabled auto-merge (squash) October 9, 2026 05:28
@buluoray
buluoray merged commit cd9c01f into main Oct 9, 2026
109 of 110 checks passed
@buluoray
buluoray deleted the fix/skip-missing-declared-resource branch October 9, 2026 05:29
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 9, 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.

Session refused when an agent template declares a file:// resource that does not exist

2 participants