fix(members): count only file resources against the document cap

[datowq]

Problem / Motivation

A private (Memory V2) member whose agent template declares many skill:// resources is refused before its first turn with Essential resource declaration exceeds the document limit (or Essential template …: too many resources through the template essentials path), even though it would load only a handful of documents — or none at all.

Why it matters

Mapping skills to an agent through skill:// entries in resources is the kiro-cli-native way to attach them, and skill-heavy templates routinely carry 60–80 such entries. Every one of those templates is unusable as a private member: the member page and the first turn both fail, and the message points at a limit the template is nowhere near. V1 members are unaffected, so the defect surfaces exactly when a user first tries private memory with an existing agent.

What changed (motivation → approach → change)

• Symptom: a template with one file:// guide and 70 skill:// entries is refused as exceeding a 64-document cap.
• Root cause: both declaration checks in member_essential_context.py compare len(resources) — every scheme — against _MAX_DOCUMENTS, while the loop that follows skips every non-file:// entry. Only file:// declarations can become documents; skill:// and knowledge:// stay on demand and are never read here (the projected_resource_documents docstring already states this). Skills were charged against a budget they never spend.
• Change: add _declared_document_count() — the number of file:// declarations — and use it at both check sites (documents_for_member and _resource_paths). The cap itself, its messages, and the separate cap on resolved documents are unchanged, so 65 file:// declarations are still refused and a glob that expands past 64 files still stops the turn.

Tests

• test_document_cap_ignores_on_demand_resource_schemes — one file:// guide plus 70 skill:// entries loads exactly one document through both documents_for_member and projected_resource_documents. Fails on main with too many resources; passes with the fix.
• test_document_cap_still_bounds_declared_file_resources — 65 file:// declarations are still refused by both paths with the existing messages, so the fix does not weaken the limit.

The full test/test_member_essential_context.py file passes (97 tests). black, isort, flake8 and mypy are clean on both changed files.

Manual verification

Declared the same on-disk SKILL.md both as skill://… and as file://…, plus file://guide.md and 100 more skill:// entries, then called _resource_paths and projected_resource_documents: exactly two documents come back, both from the file:// lines; the skill:// line pointing at the very same file produces nothing, and the 100 skills no longer trip the cap. On unfixed main the identical declaration is refused before anything is read.

Related Issues

Fixes #11465

Pattern harvest

Rule candidate: review-prompt
Pattern: a cap or budget is computed over an unfiltered collection while the consumer immediately filters that collection (len(xs) > N followed by for x in xs: if not pred(x): continue); the cap should count pred(x) items.

Checklist

• At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|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) — N/A: no doc describes the declaration count; the documented behavior (only file resources become essential documents) is what the code now does

Contribution License Agreement

Contributed under the project's Apache-2.0 license, per CONTRIBUTING.md.

[github-actions]

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 5e06d39

[github-actions]

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 5e06d39c8b641867f6d2cc812353bf4e0b3ba131 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

Resource lists of any length now pass the declaration check when ≤64 are file:// — confirm nothing relied on the old whole-list bound as a size guard.

What this change ships

Inventory (3 items) — 3 justified

Intent: let a private member whose template declares many skill:// resources start, since only file:// declarations ever become documents — a FIX.

1. Skill-heavy templates no longer refused as over the document cap; only file:// entries count — justified
2. A resources list longer than 64 total entries is now accepted when its file:// count fits — justified
3. Two new tests pin the fix and that 65 file:// declarations are still refused — justified

Both check sites (documents_for_member:491, _resource_paths:502) compared the unfiltered list while the loop skips non-file:// entries; the defect has a linked issue (#11465), a test that fails on base, and the base docstring already pins that skill/knowledge URIs "keep their on-demand behavior". The fix sits at cause level; no pins deleted, no new public surface (_declared_document_count is private, 2 in-file consumers), no riders.

[FIRST-PRINCIPLES-REVIEWED] 5e06d39

[github-actions]

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 5e06d39c8b641867f6d2cc812353bf4e0b3ba131 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

Nothing to check.

[DESIGN-REVIEWED] 5e06d39

[github-actions]

Opus 4.8 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 5e06d39

[github-actions]

Security Scope Review (fork) — 🔴 BLOCK (blocking)

Which legitimate operations does cf953e63fd201a7d22dd1e4c3aaad3bcab65f8a8 newly refuse? Model proposes, scripts/deny_diff.py decides — updated in place on each push. A script-confirmed regression blocks PR readiness.

no leg reported, and this was not the nothing-to-adjudicate short circuit

No [SCOPE-REVIEWED] marker for this head was produced, so the model's text is withheld: it cannot be shown to describe this revision. See the job logs.