Skip to content

fix(skills): read a pending skill's document with its own cap - #18778

Merged
iamwhatever merged 1 commit into
mainfrom
fix/18715-pending-skill-document-cap
Oct 10, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
fix/18715-pending-skill-document-cap

Conversation

@pepmach

@pepmach pepmach commented Oct 10, 2026

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: A valid generated pending skill opens for review and can be approved when its SKILL.md is larger than 4 KiB but within the generated-procedure limit.

In Kiro Crew 0.8.0, a generated pending skill appears in the candidate list but cannot be opened when its SKILL.md is over 4,096 bytes. The detail request answers pending_skill_unreadable, the panel says the candidate's files are not a plain directory, and Approve stays disabled. The reporter hit it with a 6,713-byte SKILL.md, far under the 10,240-character procedure limit the generator itself enforces.

Why it matters

Any user whose consolidation or crystallize run produces a skill with more than about 4 KiB of procedure text cannot review or approve it: the one action that applies is disabled, and the error points at a broken tree that does not exist. The queue fills with candidates that look wrong and cannot be cleared except by dismissing them.

Not a goal

  • Changing the approval decision, the tree fence, the link checks, or MAX_SCRIPT_BYTES for bundled scripts.
  • Raising the generator's procedure limit or changing what it writes.
  • Reviewing a candidate whose SKILL.md or .meta.json is over the document cap (51,200 bytes). Only a direct write such as the crystallize skill can produce one, and the detail read refuses it whole by design: the read stays bounded and never serves a partial view.
  • Changing the pending_skill_unreadable wording in the dashboard.

What changed (motivation → approach → change)

The pending-skill detail reader in src/kiro_crew/skills.py read the candidate's SKILL.md and .meta.json through the pin with max_bytes=MAX_SCRIPT_BYTES, the 4 KiB per-file cap meant for bundled executable scripts. The generator may write a procedure of AUTO_SKILL_MAX_PROCEDURE_CHARS (10,240) characters, so any valid document past 4 KiB failed the bounded read and was refused as if its tree were not plain.

The two document files now read under their own cap, _PENDING_DOCUMENT_MAX_BYTES, defined beside the procedure limit it derives from: four bytes per character for the body (the UTF-8 maximum) plus one more limit's worth of headroom for the frontmatter, which also covers .meta.json. The script cap is untouched and still bounds every file under scripts/. The pin semantics are unchanged: a document over the new cap still refuses the whole candidate, and the read is bounded and never partial. The owning spec, docs/system-specs/modules/memory-skills-hooks.md, names the two caps and what each bounds.

Area Change
src/kiro_crew/skills.py _PENDING_DOCUMENT_MAX_BYTES derived from AUTO_SKILL_MAX_PROCEDURE_CHARS; the SKILL.md and .meta.json reads use it
test/test_skill_pending.py, test/test_skills_composition_contract.py Tests for both caps; the contract's oversized-body test now asserts the document cap
docs/system-specs/modules/memory-skills-hooks.md The two caps documented under the pending review contract and the pending_skill_unreadable row

Backwards compatibility

Compatible: the change only widens what the detail read accepts for two document files; nothing that opens today stops opening, and scripts keep their cap.

Removes nothing: no path, key, record or function is removed or renamed.

Tests

  • test_detail_serves_a_generated_document_over_the_script_cap: a candidate staged through the generator with a 6,713-byte SKILL.md opens, the whole body is served, and approve_pending_skill_checked promotes it. Red on main: AssertionError: a valid generated document over the script cap was refused.
  • test_a_bundled_script_over_the_script_cap_is_refused: the same 6,713 bytes as a script under scripts/ still refuse the candidate.
  • test_a_document_over_the_document_cap_is_refused_whole: a SKILL.md exactly at the document cap is served; one byte over refuses the candidate, which stays staged.
  • test_metadata_over_the_document_cap_refuses_the_candidate: .meta.json over the cap refuses the candidate rather than serving empty metadata.
  • TestThePinnedPendingRead::test_an_oversized_body_refuses_the_candidate (composition contract): a body over the script cap is served; one over the document cap is refused.

Local runs: the skills test modules serially (1,835 passed), the change-related backend set (24,706 passed; 50 failures are the same ids that fail on a pristine origin/main checkout, all host-environment tests outside this change), the change-related frontend set (11,176 passed), isort, flake8, mypy, black, the comment-history and brand gates, docs-lint, the flake-pattern ratchet and the repository's semgrep rules. Local pre-push review lanes ran on this diff: GPT found one real finding (the exact-byte test fixtures depended on text-mode newline translation, fixed), Opus returned no findings, and First Principles passed with every shipped mechanism justified; the final rebase changed no diff content.

Manual verification

N/A: unit coverage sufficient. The failing read is exercised directly through get_pending_skill on a candidate the generator staged, which is the path the dashboard detail endpoint calls.

Screenshots / video

None: no user-visible frontend change. The dashboard's existing detail view simply loads for candidates it refused before.

Related Issues

Fixes #18715

Pattern harvest

Rule candidate: review-prompt
Pattern: a byte cap named for one kind of file (executable scripts) reused on a read of another kind (prose or metadata) whose producer has a different, larger limit.

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.

@pepmach
pepmach requested review from a team and KiroCrewCaptain as code owners October 10, 2026 07:54
@pepmach
pepmach requested a review from dodgeblaster October 10, 2026 07:54
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 10, 2026
@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision bb09144643cc7d78d2f5d008a4d05a45e25575ef 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 10, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

Check that an existing candidate refused by the old 4 KiB read now opens in the dashboard. Only get_pending_skill is tested directly; the dashboard endpoint is not.

[DESIGN-REVIEWED] bb09144

Description read

[DESCRIPTION-READ] 9b27ccd65f58cd0593af1c428de2eb5ec728ed4c3591ec9a7a33903f31a0fe86

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

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of bb09144643cc7d78d2f5d008a4d05a45e25575ef — 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 before merge: a promoted candidate's live read still has no cap tighter than _PENDING_DOCUMENT_MAX_BYTES (51,200), so nothing that opens for review fails after Approve.

What this change ships

Inventory (4 items) — 4 justified

Intent: let a user open and approve a generated pending skill whose SKILL.md is over 4 KiB but inside the generator's procedure limit. This is a FIX for #18715, and the PR adds a test that fails on base.

  1. A pending candidate with a SKILL.md between 4 KiB and 51,200 bytes now opens for review, and Approve is enabled — justified
  2. A .meta.json over 4 KiB no longer refuses the candidate; it is now bounded by the same document cap — justified
  3. A SKILL.md or .meta.json over 51,200 bytes still refuses the whole candidate as pending_skill_unreadable — justified
  4. The spec names the two caps and what each one bounds — justified

[FIRST-PRINCIPLES-REVIEWED] bb09144

Description read

[DESCRIPTION-READ] 117764e8035ab0db5df71a3797a932eb1dc19c7804e95f5e0315f3908dfe0fe3

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] bb09144

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

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

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] bb09144

False positive or not applicable? A repository writer can comment:
/ai-review override gpt bb09144643cc7d78d2f5d008a4d05a45e25575ef: <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 10, 2026
@pepmach

pepmach commented Oct 10, 2026

Copy link
Copy Markdown
Contributor Author

CI note, head 59f96e2: Build Wheel, Build Desktop (ubuntu-22.04), Build Desktop (ubuntu-22.04-arm) and E2E (stub ACP backend, offline) fail in their Build frontend step on gen-ui-index: src/kiro_crew/docs/ui-index.generated.json is stale. Inherited from main: this PR touches no website file and not the index, and main's own Build run on d3f462f fails on the same line (https://github.com/kirodotdev/KiroCrew/actions/runs/38036318549). Not rerun, since the result is deterministic until main carries the regenerated index (#18753 or its successor); this branch will be rebased once it does.

@pepmach

pepmach commented Oct 10, 2026

Copy link
Copy Markdown
Contributor Author
  • Check that the crystallize skill's direct writes, which have no character limit, stay under 51,200 bytes in practice. Larger ones still show as unreadable.

rebutted (checked, holds as described): src/kiro_crew/builtin_skills/crystallize/SKILL.md writes SKILL.md and .meta.json directly and states a size limit only for scripts (4 KB, step 3); nothing in the repository bounds the document, so the cap cannot be guaranteed mechanically, only sized: 51,200 bytes is five times the generator's own 10,240-character procedure ceiling (AUTO_SKILL_MAX_PROCEDURE_CHARS), and the skill's template is a frontmatter block plus When to use / Steps / Gotchas prose for one successful route.
Over the cap: PinnedDirectory._read_bytes refuses the file with OSError (EFBIG) before any byte is served, get_pending_skill returns None, the detail answers pending_skill_unreadable, and SkillsTab.tsx holds Approve while Dismiss stays available. That is the answer main gives today for every document over 4,096 bytes, so this head removes refusals and adds none.
Boundary pinned by test_a_document_over_the_document_cap_is_refused_whole: exactly at the cap is served whole, one byte over refuses the candidate, which stays staged. Recorded in the body's Not a goal section.

@pepmach

pepmach commented Oct 10, 2026

Copy link
Copy Markdown
Contributor Author
  • Check that SKILL.md files the crystallize skill writes directly stay under 51,200 bytes. A larger one still answers pending_skill_unreadable with Approve disabled, which the Not-a-goal section accepts on purpose.

rebutted (checked, holds as described): the crystallize skill (src/kiro_crew/builtin_skills/crystallize/SKILL.md) sets no byte bound on the document it writes, only on scripts (4 KB), so a direct write over 51,200 bytes is possible in principle and is refused whole on purpose: the read is bounded and never serves a partial view, which is the same fence the script read has always had.
The refusal is the existing one, not a new one: on main every document over 4,096 bytes already answers pending_skill_unreadable with Approve held; this head moves the line to five times the generator's 10,240-character procedure ceiling, so every candidate the generator can stage opens, and only a hand-written document past 51,200 bytes keeps today's answer.
Pinned by test_a_document_over_the_document_cap_is_refused_whole and TestThePinnedPendingRead::test_an_oversized_body_refuses_the_candidate; the candidate stays staged, so Dismiss still clears it. Stated in the body's Not a goal section.

The pending-skill detail reader read the candidate's SKILL.md and .meta.json
through the pin with max_bytes=MAX_SCRIPT_BYTES (4096), the per-file cap for
bundled executable scripts. The generator may write a procedure of
AUTO_SKILL_MAX_PROCEDURE_CHARS (10,240) characters, so every valid generated
skill whose SKILL.md grew past 4 KiB came back as pending_skill_unreadable,
the panel described it as not a plain directory, and Approve stayed disabled
for a candidate approve would have promoted.

The two document files now read under _PENDING_DOCUMENT_MAX_BYTES, derived
from the procedure limit: four bytes per character for the body (UTF-8's
maximum) plus one more limit's worth of headroom for the frontmatter, which
also covers .meta.json. MAX_SCRIPT_BYTES is unchanged and still bounds every
file under scripts/. A document over the new cap still refuses the candidate
whole; the read stays bounded and never serves a partial view. The approval
decision, the tree fence and the link checks are untouched.

Tests: the reporter's 6,713-byte generated document opens and approves (red
on main); the same size as a bundled script is still refused; a document
exactly at the cap is served and one byte over is refused; .meta.json over
the cap is refused. The composition contract's oversized-body test, which
asserted the old behaviour, now asserts the document cap. The owning spec
names the two caps and what each bounds.

Fixes #18715
@pepmach
pepmach force-pushed the fix/18715-pending-skill-document-cap branch from 59f96e2 to bb09144 Compare October 10, 2026 09:44
@pepmach

pepmach commented Oct 10, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto main d32c084; the single commit is unchanged (same patch), head bb09144.

@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 labels Oct 10, 2026
@pepmach

pepmach commented Oct 10, 2026

Copy link
Copy Markdown
Contributor Author
  • Check that an existing candidate refused by the old 4 KiB read now opens in the dashboard. Only get_pending_skill is tested directly; the dashboard endpoint is not.

rebutted (checked, holds): the detail endpoint api_skill_pending_detail (src/kiro_crew/dashboard/handlers/prompts.py, GET /api/skills/-/pending/{slug}) is a thin adapter this PR does not touch: it calls skills.get_pending_skill(slug) in the discovery executor and maps None to the 404 pending_skill_unreadable / pending_skill_not_found codes, and test/test_skill_pending_api.py::test_detail already drives that real handler over a real staged candidate.
Probe on this head, real handler over a generator-staged candidate whose SKILL.md is 6,285 bytes: status 200, content served whole (6,285 chars), no error code. The refusal before this change is pinned by test_detail_serves_a_generated_document_over_the_script_cap, which is red on main.
An endpoint-level copy of the size test would add a second test of the same read behind an unchanged adapter; the size behaviour belongs to get_pending_skill, where the PR tests it.

@pepmach

pepmach commented Oct 10, 2026

Copy link
Copy Markdown
Contributor Author
  • Check before merge: a promoted candidate's live read still has no cap tighter than _PENDING_DOCUMENT_MAX_BYTES (51,200), so nothing that opens for review fails after Approve.

rebutted (checked, holds): an approved candidate moves to the global skills directory as auto/<slug> (approve_pending_skill, dest = self._dir / name), and global bodies are read by _read_global_skill_text with max_bytes=None, which is the shared file safety cap hooks.MAX_FILE_BYTES (50 MB); the paged reader delivers whole up to SKILL_READ_CAPACITY (99,000 bytes) and pages beyond it. Neither is tighter than 51,200. PROJECT_SKILL_BODY_CAP (24,750) applies only to a project's own .kiro/skills and never to a promoted auto skill.
Probe on this head at the boundary: a staged candidate whose SKILL.md is exactly 51,200 bytes opens for review (content served whole), approve_pending_skill_checked promotes it to auto/cap-helper, and load_skill("auto/cap-helper") returns all 51,200 bytes.
Approve itself puts no byte bound on SKILL.md or .meta.json; scripts keep MAX_SCRIPT_BYTES, unchanged by this PR.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 10, 2026

@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 generated pending skills whose SKILL.md is over 4 KiB. The detail read refused them as pending_skill_unreadable with Approve disabled, because it read the two document files under MAX_SCRIPT_BYTES, the 4 KiB cap meant for bundled scripts. The root cause is fixed: SKILL.md and .meta.json now read under _PENDING_DOCUMENT_MAX_BYTES, which is derived from AUTO_SKILL_MAX_PROCEDURE_CHARS (4 bytes per char plus one limit of frontmatter headroom, 51,200 bytes). Scripts under scripts/ keep the 4 KiB cap. The read stays pinned and bounded, and an over-cap document still refuses the whole candidate. The approve path's own checks (layout, links, validate_scripts, redaction) are untouched, so this widens only what the review panel can display, not what can be promoted. The tests go through the generator with the reported 6,713-byte document and are red on main. They also pin the exact-cap and one-byte-over boundary, the script cap, and metadata over the cap. Checks are green on bb09144. GPT and Opus have no findings, Design and First Principles are PASS, and the author answered both lanes' items on this head. — crew-pr-reviewer

@iamwhatever
iamwhatever enabled auto-merge (squash) October 10, 2026 19:06
@iamwhatever
iamwhatever merged commit 549681e into main Oct 10, 2026
102 checks passed
@iamwhatever
iamwhatever deleted the fix/18715-pending-skill-document-cap branch October 10, 2026 19:06
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 10, 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.

Pending skill reader applies the 4 KiB script limit to SKILL.md, disabling approval

2 participants