Skip to content

docs: add context-management guide - #12156

Merged
chenmingwei23 merged 1 commit into
mainfrom
docs/context-management
Sep 20, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
docs/context-management

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Nobody can answer "what is actually in the model's context right now?" from the
docs. The facts exist, but they are spread across context.py, skills.py,
subagent.py, members.py and four module specs, so every question — what does
the first turn carry, what repeats each turn, what does a sub-agent see, why does
a custom agent get no skills — needs a code read. Two questions have no written
answer at all: which crew-member private files exist today, and why a dispatched
kirocrew-worker never matches a skill trigger.

Separately, src/kiro_crew/docs/memory-and-learning.md states a decay table as
if those history bodies reach the prompt. They do not: a new session carries a
bounded index and memory_recall fetches bodies on demand.

Why it matters

Getting this wrong wastes real work. A maintainer who believes daily history is
injected at session start debugs the wrong thing. A brief staged in
$KIROCREW_SCRATCH is unreadable to a dedicated-process sub-agent, which reads
as a broken sub-agent. And a worker told to "follow the prepare-pr skill" cannot
find it, because its agent spec carries no skill:// entry — a silent gap that
costs a whole dispatch.

A doc full of restated constants has its own failure mode, which is why this ships
a gate rather than just prose: docs_lint.py checks a doc's symbols and paths but
never its VALUES, so 858 survives a change to _MEMORY_PREFS_CAP with lint
green and the doc quietly lying.

What changed (motivation → approach → change)

A new contributor document, a test that keeps it honest, a router row so a code
change reaches it, one corrected sentence in an existing doc, and cross-tree links
so readers still find it.

File What it does
docs/architecture/context-management.md new: six questions, answered from the code on this base
test/test_context_management_doc.py new: pins the doc's numbers and rules to the constants and functions they cite
AGENTS.md new router row: a change to context.py / context_blocks.py now points here, so the same-commit update rule reaches this doc
src/kiro_crew/docs/memory-and-learning.md fixed: the decay tiers govern a dated read, not search, and a new session carries an index rather than bodies
docs/architecture/README.md indexes the new doc
src/kiro_crew/docs/index.md, README.md link across to it

The doc is ordered as the six questions a maintainer asks, with a table wherever
the answer has a shape: the first-turn block order and every budget with its
symbol; what repeats per turn and what returns after compaction; a sub-agent's
three include_* switches and why its scratch dir differs; the four-row
skill-mapping table and what "lazy skill loading" means; a crew member's four
identity layers and the session_create agent-inheritance rule; and a
per-capability audit of crew-member private files marked implemented, partial or
not implemented with evidence.

It lives in docs/architecture/ rather than the packaged tree because it cites
private symbols throughout, and src/kiro_crew/docs/README.md routes an
engineering note to docs/. The packaged index links across with the repository
URL every other packaged-to-contributor link already uses, since a relative path
would not resolve inside an installed wheel.

Two facts in it are easy to get backwards and are stated plainly: per-turn skill
trigger matching is off by default (skills.max_triggered is 0), and the
[work ledger] snapshot rides on monitor / auto-nudge cycle messages, not on
every turn. Two orderings that a table alone would misreport are called out: a
Memory V2 member's essentials envelope is spliced in after the critical-rules
block ahead of every other row, and a mapped agent gets its skills on both
backends — only the loader differs, kiro-cli natively versus Kiro Crew injecting.

The test is what makes the numbers safe to restate. It reads the budgets table out
of the doc and asserts each literal equals the constant the same row names, then
asserts the behavioural tables against the code that implements them —
_skills_injection_plan is called for all four rows rather than having its source
scanned, resources is asserted absent from _WORKER_MIRRORED_SHAPES, every
_mark() label must appear in the timing list, and every CAPABILITY_SECTIONS
entry must appear in the permission row. A constant that moves, a new timing label
or a new capability section fails this test instead of silently aging the doc.

Citations name a file and a symbol, not path:line, because docs_lint.py's
line-ref check rejects line numbers and directs authors to cite a symbol.

Backwards compatibility

Compatible: six markdown files and one new test. No code, schema, config key or
command changes. Nothing is removed from the wheel that was ever released in it —
the new doc never shipped in a release, and it was deliberately absent from
tips_allowlist.py, so it could not surface as an in-app feature tip.

Tests

test/test_context_management_doc.py, 24 tests, all new. It pins SHARES, never
byte figures, because docs/system-specs/common/code-style.md owns the rule that
context budgets are read as fractions of the base:

  • 8 parametrised rows recompute each _budget(...) share from the live constants
    (cap / _CONTEXT_BUDGET_BASE) and compare it to the percentage the doc states:
    _MEMORY_PREFS_CAP, _MEMORY_PROJECTS_CAP, _MEMORY_HISTORY_CAP,
    _LESSONS_CAP, _SEMANTIC_MEMORY_CAP, _SKILLS_CAP, _STEERING_CAP,
    _PREAMBLE_HEADROOM.
  • 2 more do the same for thread history against its own reference base:
    _HISTORY_BUDGET_CHARS and _COMPRESSED_HISTORY_CAP as shares of
    _HISTORY_REFERENCE_BASE.
  • One forbids a \d{1,3},\d{3} literal anywhere in the shares table, so byte
    figures cannot drift back in beside a share.
  • The rest assert that the ledger snapshot, activity_index default, member caps
    and activity-log rotation are NAMED rather than quoted; that the
    protected-ceiling factors and MIN_TRIGGER_OVERLAP match; the three stated
    config defaults; the four-row skill-injection truth table, asserted by calling
    _skills_injection_plan rather than reading its source; the unmirrored
    resources key; complete CAPABILITY_SECTIONS coverage; and complete _mark()
    label coverage.

Every pin was proven to fail rather than merely pass, with the mutated file
restored byte-identical after each:

Mutation Test that reds
_SKILLS_CAP → _budget(0.20) test_share_table_matches_the_fraction_in_code[_SKILLS_CAP-6600]
_HISTORY_BUDGET_CHARS → * 0.30 test_history_shares_match_their_own_reference_base[_HISTORY_BUDGET_CHARS-49500]
re-adding 4,950 to the skills row test_no_byte_literals_in_the_shares_table

Manual verification

Every claim was read out of the code on this base, and an independent review pass
re-verified 38 of 38 of them against the same modules, finding none wrong.

  • python3 scripts/docs_lint.py --test and ./scripts/docs-lint.sh → pass, no new baseline triples. This is the gate that matters most here: the file moved between doc trees, which rewrote 11 relative links and required an index row, and link resolution plus reachability are exactly what it checks.
  • run_scoped_tests.py --surface backend → 24 passed
  • check_brand_name.py, check_feature_map.py, check_changelog_history.py, check_comment_history.py, check_testpaths_coverage.py, check_per_file_coverage.py, check_sync_io_in_async.py → pass
  • black --check and flake8 on the new test file → clean

Spot-checked on this host: ~/.kiro/agents/kirocrew-worker.json carries
resources: ["file://.kiro/steering/**/*.md"] and no skill:// entry, which is
the §4 claim; and a member directory holds activity.jsonl with briefing.md
absent until written, which is the §6 claim.

Related Issues

no linked issue: documentation gap raised directly, not tracked as an issue.

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)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and smeyffret September 20, 2026 02:33
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Intent: Give a maintainer one authoritative, code-derived account of what reaches the model's context — the first-turn block order, what repeats per turn, what a sub-agent sees, why a custom agent gets no skills, how a crew member's session is built, and which crew-member private files exist today.
Not a goal: changing any behaviour, restating what agents.md / skills.md / subagents.md / memory-and-learning.md / the module specs already cover, or adding line-number citations (the docs-lint line-ref check rejects them; citations name a symbol).

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 20, 2026
@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 5aa6bb0

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

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

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

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

Design-Verdict: PASS

Spot-check the §1 block-order table against build_session_context — it is the doc's centerpiece and the one table the pinning test leaves unenforced.

Suggestions

  • Extend the pinning mechanism to §1: assert the table's block sequence against context_blocks._MARKERS (or the order of _mark() stamps), so the doc's most-read table gets the same drift protection as the budgets.

[DESIGN-REVIEWED] 5aa6bb0

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 5aa6bb05e1634ce060242ff7322aabe7af99732d and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 5aa6bb0

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

@github-actions

github-actions Bot commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — ✅ PASS

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

The test pins shares and four behaviour tables; the 20-row block order and per-turn table rest only on the author's read — spot-check those against build_message before merge.

What this change ships

Inventory (7 items) — 7 justified

Intent: let a maintainer answer "what is in the model's context" from docs instead of reading five modules — an ADDITION (with one declared doc fix riding in).

  1. New contributor guide answering six context questions — justified
  2. New test pinning the doc's shares and rule tables to live constants — justified
  3. AGENTS.md router row so context.py changes reach the doc — justified
  4. Corrected decay claim in memory-and-learning.md (dated read, not context injection) — justified
  5. Architecture README index row for the new doc — justified
  6. Packaged index links across via repository URL — justified
  7. Packaged-docs README cites the new doc as its routing example — justified

Verified: the eight share constants in context.py:1020-1079 match the doc's percentages exactly; _skills_injection_plan (context.py:2740) returns (is_cc if globs else not is_custom), matching the four-row table; get_context(include_activity=False) plus activity_index (memory.py:1156, memory.py:1208) ground the item-4 rewrite of the old "not loaded into context" pin; docs_lint.py carries exactly the path-exists/line-ref/dead-identifier checks and no value check, so item 2 duplicates nothing; grep for the cap names across docs/ finds only the new file, so the budgets are documented once; doc-contract tests and packaged-to-contributor GitHub links (11 existing) are established patterns.

[FIRST-PRINCIPLES-REVIEWED] 5aa6bb0

@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 Sep 20, 2026
@iamwhatever
iamwhatever force-pushed the docs/context-management branch from 0e447af to f7658e0 Compare September 20, 2026 03:06
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: test/test_context_management_doc.py — pins the doc's numeric table and behavioural tables to the constants and functions they cite.

  • fixed: docs_lint gates symbols and paths but not values or ordering, so a restated constant can silently rot — span=264eab3e4867

Legitimate, and the strongest item in this round. docs_lint.py's fact checks
are path-exists and dead-identifier; neither reads a VALUE, so 858
survives a change to _MEMORY_PREFS_CAP with lint green.

Took the first of the two clearing conditions ("a test pins the doc's numeric
table against the module constants"), not the second (drop the values): the
numbers are the reason the section is useful, and the gate makes them safe.

test/test_context_management_doc.py (new, 25 tests) reads the budgets table
out of the doc and asserts each literal equals the constant its own row names,
across _CONTEXT_BUDGET_BASE, the eight _budget(...) caps,
PROJECT_SKILL_BODY_CAP, _EPISODIC_INJECT_CAP, _HISTORY_BUDGET_CHARS,
_COMPRESSED_HISTORY_CAP, _PER_MESSAGE_CAP, _SNAPSHOT_MAX_CHARS, the
activity_index default and the protected-ceiling factors.

Ordering is covered too, which the finding named separately: every
_mark() label in context.py must appear in the doc's timing list, and every
CAPABILITY_SECTIONS entry must appear in the §6 permission row, so a new
label or section fails the test rather than aging the doc.

Proven to fail rather than merely pass: mutating _MEMORY_PREFS_CAP to
_budget(0.030) reds test_budget_table_matches_the_constant[_MEMORY_PREFS_CAP-990]
with a message naming the doc and the live value. context.py restored
byte-identical after.

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

iamwhatever commented Sep 20, 2026 •

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: test/test_context_management_doc.py — the gate this item's second clearing condition asks for.

  • fixed: Item 2, oversized — the budget table hardcodes literals that no gate compares to code — span=6207da519fa7

Same root cause as the design lane's WATCH item, and the finding states the
remedy as a disjunction: delete the literals, or have a gate that compares
them to code. Took the gate.

test/test_context_management_doc.py asserts all 15 of the cited literals
against their constants, plus the inline 0.7, 4,000 and 1,600
(MIN_TRIGGER_OVERLAP, MEMBER_BRIEFING_MAX_CHARS / MEMBER_RULES_MAX_CHARS,
_SNAPSHOT_MAX_CHARS). Nothing in the doc's numeric surface is now unpinned.

Chose the gate over deletion because the values are the section's whole use:
"skills get 15% of the shared allowance" answers a budgeting question that
"skills get _SKILLS_CAP" does not, and a reader who must resolve nine symbols
by hand is a reader who does not check. AGENTS.md's objection to a restated
count is that it goes stale unnoticed — the gate removes "unnoticed", which is
the load-bearing half.

Red-before evidence is in the sibling design-lane disposition for the WATCH item.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: none added — a mechanism was REMOVED (the drift callout) and the underlying stale sentence corrected.

  • fixed: Item 3, symptom-level — a drift note published instead of the fix — span=4eeafdff31ae

Legitimate and correctly scoped. Publishing "the other doc is wrong" is worse
than a silent inconsistency: it tells a reader the stale sentence is known-bad
and still leaves it on the page they land on first.

Took the subtraction verbatim. Deleted the > **Drift:** callout, and corrected
src/kiro_crew/docs/memory-and-learning.md: the decay tiers now describe what a
READ returns, with an added sentence naming what a new session actually carries
(a bounded index of the last three days, bodies on demand via memory_recall).
The tier line "retained on disk but not loaded into context" became "retained on
disk, not returned by a read", since "loaded into context" was the wrong axis.

Also removed the intro's promise to flag drift inline: with the one drift fixed
at source there is nothing left to flag, and leaving the promise would invite
the next author to annotate rather than fix.

Scope note: this takes the diff to a third markdown file. Accepted because the
stale sentence is the CAUSE, it is docs-only, and the alternative was shipping a
note about a defect I could fix in the same PR.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: test/test_context_management_doc.py serves this coupling; no filename-table entry added.

  • fixed (by a stronger mechanism than the one suggested): register content coupling between the doc and context.py / context_blocks.py — span=4dc867cc621f

Agreed on the goal, took a different mechanism, so recording the divergence
rather than claiming the suggestion verbatim.

CODE_COUPLED_DOCS in scripts/docs_lint.py is a FILENAME coupling: it catches
a rename or deletion of the partner file. It cannot notice that
_MEMORY_PREFS_CAP changed value or that _MARKERS was reordered, which is the
failure this doc is actually exposed to — so an entry there would read as
protection while leaving the real gap open.

The new test couples on CONTENT instead: it fails when a constant moves, when
context.py gains a _mark() label the doc does not list, when
CAPABILITY_SECTIONS gains an entry, when resources becomes mirrored onto the
worker spec, or when _skills_injection_plan's truth table changes — asserted by
calling it, so a behaviour-preserving rewrite stays green and a behaviour change
reds.

Not claiming it forces a doc touch in the same COMMIT for every edit to
build_message: it forces one for every edit that changes a fact the doc states,
which is the subset worth gating. A broader "any touch to context.py requires a
doc touch" rule would fire on unrelated refactors and be routed around.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: none — this item asks where the file lives, which is a maintainer's call.

  • needs-a-decision: Item 1 — the packaged tree's charter routes an engineering note to docs/ — span=8090704acc9b

Question for a maintainer: should this file live in docs/architecture/
instead of src/kiro_crew/docs/?
I did not move it unilaterally because the
brief that commissioned it named the packaged path, and moving it changes what
ships in the wheel.

The finding is well-grounded. src/kiro_crew/docs/README.md says: "Because every
doc here reaches every user, keep the content task-oriented and free of internal
design narration. An engineering note belongs in [../../../docs/] instead."
Every citation in this doc is into a private symbol (_skills_injection_plan,
_build_member_section), which no user acts on.

Two facts cut the other way, which is why I am asking rather than moving:

  1. The "first paragraph is read verbatim as a feature description" hazard does
    NOT apply. tips_allowlist.py is an explicit allowlist and this file is absent
    from it, so it cannot surface as an in-app tip.
  2. The packaged tree has a real runtime consumer for exactly this content: the
    [DOCUMENTATION] context block points the agent at the packaged docs dir, so an
    agent asked "why did my skill not load?" can read this file at runtime. In
    docs/ it is outside the wheel and unreachable that way.

On the duplication half of the item: an independent review pass compared this
file against docs/system-specs/modules/memory-skills-hooks.md and found no
harmful duplication — this documents assembly ORDER and provenance and defers
inline, which the spec does not cover.

The option I would take: git mv to docs/architecture/context-management.md,
keep the index link as a cross-tree reference, and accept losing the runtime
read — the charter is explicit and a doc citing private symbols is not end-user
material. Say the word and I will move it in this PR.

@iamwhatever
iamwhatever force-pushed the docs/context-management branch from f7658e0 to 6f06052 Compare September 20, 2026 03:13
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: none added — the file was relocated and two cross-tree links added; nothing new to maintain.

  • fixed: Item 1 — the packaged tree's charter routes an engineering note to docs/ — span=8090704acc9b

Maintainer ruled: move it. Superseding my earlier needs-a-decision on this
span with the resolution.

git mv src/kiro_crew/docs/context-management.md docs/architecture/context-management.md. The charter is explicit —
src/kiro_crew/docs/README.md: "keep the content task-oriented and free of
internal design narration. An engineering note belongs in docs/ instead" — and
every citation in this doc is a private symbol, so the finding was right.

The move is not just a rename. It rewrote 11 relative links inside the doc: the
seven packaged siblings became ../../src/kiro_crew/docs/*.md and the four
specs went from ../../../docs/system-specs/ to ../system-specs/. It also
needed an index row in docs/architecture/README.md, without which docs-lint
fails the doc as unreachable. ./scripts/docs-lint.sh is green after the move
with no new baseline triples, which is the check that actually proves the links
and reachability survived.

Readers are not stranded: src/kiro_crew/docs/index.md keeps a one-line
cross-tree link, and the README.md sentence that states the packaged/contributor
rule now cites this doc as its example — so the pointer sits beside the rule that
explains why it is not in that tree.

The accepted cost, stated plainly: the [DOCUMENTATION] context block points an
agent at the packaged docs dir, so this file is no longer readable by an agent at
runtime. test/test_context_management_doc.py follows the file and still passes
(25 tests).

@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 Sep 20, 2026
@iamwhatever
iamwhatever force-pushed the docs/context-management branch from 6f06052 to 4a4223b Compare September 20, 2026 03:52
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: AGENTS.md router row — context.py / context_blocks.py now routes to this doc.

  • fixed: the doc is unrouted, so a build_session_context change is never pointed at it — span=9265292b7134

Legitimate, and it is the gap that would have aged this doc fastest. The test I
added last round pins values, labels and the injection plan, but the block-order
table, the per-turn table and the precedence claims are prose — nothing makes an
author who edits build_session_context even look here.

Took the stated clearing condition: added a router row to AGENTS.md beside the
existing memory/skills/hooks row —
| `context.py`, `context_blocks.py`, what reaches the model's context |
→ context-management. That is the table the same-commit update rule reads, so
the routing now exists for the prose the test cannot pin.

Chose AGENTS.md over the memory-skills-hooks spec of the two options offered:
the router is what an author consults by file path, and this doc spans
context.py, skills.py, subagent.py and members.py rather than sitting
under one module spec.

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

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: none added — a broken link form replaced with the repository URL convention.

  • fixed: the packaged index used a relative path that does not exist in an installed wheel — span=94106cd5d096

Legitimate, and a defect I introduced with last round's move. index.md is the
IN-APP entry point, read from the installed package, where ../../../docs/ does
not exist — and the [DOCUMENTATION] block steers the agent to consult local
docs from exactly that directory, so the dead link lands in front of an agent.

Took the stated clearing condition and the existing convention: the entry now
uses https://github.com/kirodotdev/KiroCrew/blob/main/docs/architecture/context-management.md,
which is what every other packaged-to-contributor link already does
(channel-capabilities.md, dynamic-subagent-sizing.md, mcp-apps.md). The
line also says plainly that it is a contributor document in the repository and
not part of the installed package, so a reader knows why it leaves the wheel.

src/kiro_crew/docs/README.md deliberately keeps its relative link: that file
is the repo-browsing index ("the same set, organized for someone browsing the
repository") and already links ../../../docs/README.md the same way, so a URL
there would be the inconsistent choice.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: none added — an overclaiming sentence corrected.

  • fixed: "the tiers above describe what recall can reach" is false; indexed recall searches full history files — span=1bc0515e7121

Correct, and it falsifies a sentence I wrote last round while fixing a different
defect. Verified before changing: memory.py → _index_file indexes each
history file's COMPLETE content into the FTS table, so MemoryStore.search
reaches a line from a day that read_recent_history's decay would have collapsed
to a date and a count. Tying the tiers to recall understated what recall can find.

Took the suggested fix, scoping the tiers to the dated read: the tiers now
"govern a dated READ (read_recent_history), not search", with the reason stated
— the full-text index holds the complete content, so recall can still surface a
collapsed day's line.

Kept the part of the sentence that was right and is the reason it exists: a new
session carries none of these bodies, only a bounded index of the last three
days' headings, and the body arrives when memory_recall asks. That is the
original inaccuracy this edit set out to fix.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: none added — link form corrected to the repository URL.

  • fixed: the relative contributor-doc link is absent from installed wheels — span=cfc239ad5964

Correct. src/kiro_crew/docs/index.md is read from the installed package, where
../../../docs/architecture/ does not exist, so the link was dead for every
reader who is not in a repo checkout.

Fixed as suggested with the repository-hosted URL, matching the convention the
other packaged docs already use for contributor targets. The entry also now says
it is a repository document rather than part of the installed package.

Same root cause as the design lane's watch item on this line; both are answered
by this one change, each in its own lane's record.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: none added — two order/ownership claims made exact.

  • fixed: the block order is wrong for a V2 member, and "Claude Code backend only" omits kiro's native loading of mapped skills — span=c00cc8cdf7cd

Both legitimate; this span covers two lines and both are now exact.

V2 ordering. Verified: the last step of build_session_context is
context = prefix + essentials + context[len(prefix):], so a V2 member's
essentials envelope is spliced in immediately AFTER the critical-rules block and
ahead of every other block — not at the member row's position. Added an explicit
paragraph under the table saying so, naming _build_v2_essentials, noting that
rows 6 and 14 are suppressed for it, and marking the table as the V1 /
non-member order. Row 6's condition now reads "V1 member sessions".

Mapped skills on kiro. The table's "Claude Code backend" column described
where Kiro Crew INJECTS and read as though a mapped agent saw nothing on the
kiro backend. It sees the full mapped set there — kiro-cli loads skill://
resources itself when spawned with --agent, which is exactly why
_skills_injection_plan returns false. Rows 2 and 4 now say "on either
backend" with the loader named per backend, and a following paragraph states the
split: kiro-cli natively, Kiro Crew by injection on Claude Code, with steering
following the same rule.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

The failing backend lanes are main-inherited, not this PR

Every failing job dies at conftest import, before a single test in this diff
runs. From CI run 35489784213, Backend Tests shard 3:

src/kiro_crew/sandbox.py:1053: in <module>
    assert set(_DELEGATED_OVERLAP_LEAF_REASONS) == set(_CREW_NOFOLLOW_READONLY_FILE_LEAVES) | set(
        _CREW_NOFOLLOW_READONLY_DIR_LEAVES
    )
E   AssertionError

The import chain that reaches it:

conftest -> safety_override -> config.loader -> mcp_gateway.rewriter -> manager -> sandbox

Because the assert is at module scope, import kiro_crew.sandbox raises and the
whole session aborts at collection. Three leaves are present in the nofollow
read-only tuples with no entry in _DELEGATED_OVERLAP_LEAF_REASONS:

decisions
member-memory-bindings
subagents

Why it is not this PR

  • The assert is on the PR base (4ed7335d88), reproduced on a pristine detached checkout of origin/main, and still present at c28c78e6db.
  • This diff touches no .py source other than test/test_context_management_doc.py. sandbox.py here is byte-identical to origin/main.
  • The failing set is exactly the lanes that import kiro_crew.sandbox: 8 backend shards, IPv6 ubuntu + windows, Kernel Lock Owner, namespace sandbox, 2 E2E, Windows pod canary.
  • Every lane this PR actually exercises is green: Docs Lint, Brand Name Gate, Feature Map Gate, Changelog History Gate, Comment History Gate, Inclusive Language.
  • Main's own CI at 4ed7335d88, 363c701ac1 and 5883fb014c was cancelled by concurrency, so main has not proven itself green at any of those heads — the defect reached the branch without a red run on main to announce it.

What happens next

No push, no job reruns, and nothing in sandbox.py from me — a docs PR is the
wrong place to fix a sandbox invariant, and rerunning a deterministic import error
just repeats it. I am watching origin/main for the fix; when it lands I will
rebase onto it, push with a SHA-pinned lease, and post the usual rebase note so
this run's history is readable.

Superseding my two earlier comments on this: the first implied that holding an
older base insulated the PR, which is wrong — Actions builds
refs/pull/12156/merge, so live main reaches the run regardless of the branch's
base.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the byte-value pins were REMOVED from test/test_context_management_doc.py and replaced with share pins; the doc's table now states fractions and constant names only.

  • fixed: Item 2 — the budget base and formula were restated as byte figures against code-style.md — span=b5ba49eadc83

Withdrawing my earlier rebuttal on this span. I argued the gate made
restatement safe. That was wrong on the premise: I had not checked whether a
convention already ruled, and docs/system-specs/common/code-style.md does —
context budgets "are expressed as FRACTIONS of the base, so read them there
rather than quoting a byte figure". A maintainer has now ruled to honour it.

The table states shares and constant names, no byte literals: 16% +
_MEMORY_HISTORY_CAP, never 5,280. Every other byte figure in the doc went the
same way — the ceiling reads max(3 × the base, …), the ledger snapshot,
activity index, project-body allowance, member caps and log rotation each name
their constant instead of quoting it.

The pin did not disappear, it moved to the fraction. The 12 byte assertions are
gone; in their place the test recomputes each share from the live constants
(cap / _CONTEXT_BUDGET_BASE) and compares it to the percentage the doc states.
That is strictly stronger than what it replaced: a change to the BASE alone moves
every byte figure and no share, so the doc now survives it — which is the
convention's own argument — while a change to a FRACTION still reds the test.

A second new test forbids a \d{1,3},\d{3} literal anywhere in that table, so the
byte figures cannot drift back in as a "helpful" addition beside a share.

Both proven to fail rather than merely pass: mutating _SKILLS_CAP to
_budget(0.20) reds test_share_table_matches_the_fraction_in_code[_SKILLS_CAP-6600],
and re-adding 4,950 to the skills row reds
test_no_byte_literals_in_the_shares_table. context.py and the doc were
restored byte-identical after each. 22 tests pass; docs-lint, brand, feature-map,
black, isort and flake8 are clean.

Not yet pushed: main is still broken at sandbox.py:1053, so this is batched
with the rebase onto the first green main.

@iamwhatever
iamwhatever force-pushed the docs/context-management branch from b855540 to c241d02 Compare September 20, 2026 05:24
@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 Sep 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto 2b7d378116, which carries the sandbox fix — and this push also
brings the shares-not-bytes change.

main imports again: #12193 landed the three missing _DELEGATED_OVERLAP_LEAF_REASONS
entries (decisions, member-memory-bindings, subagents), so
import kiro_crew.sandbox no longer raises and the backend lanes can collect. The
15 reds on the previous head were that defect and nothing in this diff.

Two changes ride this single push, deliberately batched so one CI round judges both:

  1. The re-sync — c241d02921 sits directly on 2b7d378116, still the same
    seven files, no upstream work touched.
  2. Budget shares instead of byte figures, per a maintainer ruling on
    43a03531ad25 / b5ba49eadc83. docs/system-specs/common/code-style.md owns
    the rule that context budgets are read as FRACTIONS of the base rather than as a
    quoted byte figure, and the table now states 16% + _MEMORY_HISTORY_CAP
    rather than 5,280. Every other byte figure in the doc went the same way: the
    ceiling reads max(3 × the base, …), and the ledger snapshot, activity index,
    project-body allowance, member caps and log rotation each name their constant.

The pin moved rather than disappeared. The 12 byte assertions are gone; in their
place the test recomputes each share from the live constants
(cap / _CONTEXT_BUDGET_BASE) and compares it to the percentage the doc states,
plus a second test forbidding a \d{1,3},\d{3} literal in that table so the bytes
cannot drift back. That is stronger than what it replaced: a change to the base
alone moves every byte figure and no share, so the doc survives it — the
convention's own argument — while a change to a fraction still reds the test.

Verified on the new base before pushing: import kiro_crew.sandbox OK, 22 tests
pass, docs-lint clean with no new baseline triples, brand and feature-map gates
pass, body check accounts for every changed area, push_guard reports a single
commit on base. Both new gates were also proven to FAIL on real drift — mutating
_SKILLS_CAP to _budget(0.20) and re-adding 4,950 to the skills row each red
their test — with the files restored byte-identical after.

@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 Sep 20, 2026
Answers six questions about what reaches the model, from current code:
the first-turn block order, the per-turn additions, a sub-agent's scope,
why a custom agent sees no skills, how a crew member's session is built,
and which crew-member private files exist today.

Cross-links agents/skills/subagents/memory docs and the module specs rather
than restating them. Citations name a file and a symbol, since docs-lint
rejects line numbers.
@iamwhatever
iamwhatever force-pushed the docs/context-management branch from c241d02 to 5aa6bb0 Compare September 20, 2026 05:49
@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 Sep 20, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: two SHARE_ROWS-style pins added for _HISTORY_REFERENCE_BASE; the PR description's test inventory corrected to the shipped file.

  • fixed: the description's test inventory describes the pre-ruling file, and the two _HISTORY_REFERENCE_BASE shares are unpinned — span=8879aa035358

Both halves correct, and both mine. When the shares ruling landed I rewrote the
doc and the test and did not regenerate the PR body, so it still advertised "25
tests", "12 parametrised rows" asserting constants the file no longer touches, and
a mutation proof naming test_budget_table_matches_the_constant, which no longer
exists. The description described a file that had been replaced.

Corrected to the shipped file: 24 tests, 8 parametrised share rows naming the
eight _budget(...) caps, the byte-literal guard, and a table of the three
mutations with the test each one reds.

The unpinned-shares half is the sharper finding, because the doc stated 21% and
27% while nothing recomputed them — exactly the gap this PR exists to close, left
open in the change that closed it elsewhere. Two pins added against the right
base: _HISTORY_BUDGET_CHARS and _COMPRESSED_HISTORY_CAP as shares of
_HISTORY_REFERENCE_BASE, not of _CONTEXT_BUDGET_BASE.

Proven red-before: _HISTORY_REFERENCE_BASE * 0.21 → * 0.30 reds
test_history_shares_match_their_own_reference_base[_HISTORY_BUDGET_CHARS-49500];
context.py restored byte-identical.

Worth recording how the new pin was verified: my first matcher took the EARLIEST
percentage before the constant and read 21% for the compressed cap, since both
shares sit in one sentence. The test failed, which is why it now takes the nearest
preceding percentage. A pin that had passed on the wrong number would have been
worse than none.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: the two stated shares are now recomputed by the test; nothing deleted.

  • fixed: Item 2 — the doc states numeric shares the shipped test does not recompute — span=ff5bbbd93cc5

Accepting the premise as stated: a share the test does not recompute is exactly
the ungated restatement this PR was asked to remove, and 21% / 27% were in that
position.

Took the second of the two clearing conditions — "a diff that actually pins
them" — rather than deleting the figures, for the same reason the maintainer's
ruling kept shares over bytes: the share is what the code states and what
survives a change to the base, so it is worth stating once it is gated.

test_history_shares_match_their_own_reference_base recomputes both from
_HISTORY_REFERENCE_BASE and compares against the percentage in the sentence
that names each constant. After this, every numeric share anywhere in the doc is
recomputed from live code: eight _budget(...) caps against
_CONTEXT_BUDGET_BASE, these two against the history base, and no byte literal
remains for a third test to catch.

The description's inventory error that this item also names is corrected in the
sibling design-lane record for 8879aa035358.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto 7e8f2c459f; the four reds on the previous head were upstream and
are fixed by that commit.

All four traced to one defect I did not introduce. Backend Tests (3.12, 2) and
Backend Tests (Windows) (2) died in test/test_vector_memory.py:

E       AssertionError: assert [] == [('pref.os', 'macos')]
test/test_vector_memory.py:624: AssertionError
TypeError: ...test_replacing_a_real_value_still_retires_episodic_memory.<locals>.<lambda>()
           got an unexpected keyword argument 'defer_embedding'

Coverage Gate and PR Readiness then failed CLOSED because the backend surface
failed — downstream of the same thing, not independent.

Confirmed by bisecting rather than assuming: that test fails on a pristine
checkout of my old base 2b7d378116 and passes on 7e8f2c459f, whose subject
is "test(memory): accept defer_embedding in _retire_stale_episodic stubs".
Production had gained a defer_embedding kwarg that the test's stub lambda did not
accept. This PR touches no .py file except its own test.

This push also answers both open review items, and both were mine:

  • The description advertised "25 tests" and "12 parametrised rows" asserting
    constants the file no longer touches. When the shares ruling landed I rewrote the
    doc and the test and never regenerated the body. Corrected to the shipped file:
    24 tests, 8 share rows, and a table of the three mutations with the test each reds.
  • The doc stated 21% and 27% for _HISTORY_BUDGET_CHARS and
    _COMPRESSED_HISTORY_CAP with nothing recomputing them — an ungated restatement,
    the exact thing this PR exists to remove. Two pins added against
    _HISTORY_REFERENCE_BASE, proven red-before (* 0.21 → * 0.30 reds the new
    test).

Every numeric share in the doc is now recomputed from live code, and no byte
literal remains. Verified on the new base before pushing: the upstream test passes,
24 doc tests pass, docs-lint clean with no new baseline, brand and feature-map
pass, body check accounts for every area, push_guard single commit on base.

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

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: none added — deferred to #12175 item 1, which already specifies this assertion.

  • accepted-and-deferred: extend the pin to §1's block-order table against context_blocks._MARKERS — span=e4ed5173137c

Agreed on the substance, and it is the right next pin: the block-order table is
the doc's most-read shape and the only major table still unguarded, now that
every budget share, the _mark() label set, CAPABILITY_SECTIONS and the
injection truth table are all recomputed from live code.

Recording it as a CLASS, not a fourth instance. This is the same ask as
942ce2b94acb (round 1), 283624c5b64d (round 3) and dc29dc5b9d3e (round 4)
under a fourth span id, and #12175 item 1 already specifies the implementation:
assert each row's marker appears in _MARKERS, mirroring the existing _mark()
assertion, with an explicit allowlist for the markers the table deliberately
omits — the per-turn blocks §2 owns rather than the first-turn table.

Deferred rather than done here because this PR's scope is frozen, and because the
allowlist is the hard half: _MARKERS carries ~39 entries against the table's 20
rows, so a naive completeness assertion fails immediately and a wrong allowlist
would pin the table to a fiction. That deserves its own change with its own
red-before, not a sixth round on a docs PR whose every lane is green.

Issue #12175 carries the deferred-finding label, an assignee and a Due: line.

@chenmingwei23
chenmingwei23 merged commit d6e77b0 into main Sep 20, 2026
130 of 139 checks passed
@chenmingwei23
chenmingwei23 deleted the docs/context-management branch September 20, 2026 08:25
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Sep 20, 2026

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

Approved: docs-class, and it ships the gate that keeps it honest rather than prose alone. Sampled test_context_management_doc.py: it pins the doc's stated shares and formulas against the LIVE constants (_PROTECTED_CONTEXT_CHARS_PER_TOKEN, _PROTECTED_CONTEXT_WINDOW_FRACTION, _PROTECTED_CONTEXT_FLOOR, MEMBER_BRIEFING_MAX_CHARS, _EPISODIC_MEMORY_CAP) and refuses byte literals in the shares table, so the doc names constants instead of quoting values that docs_lint.py would never re-check. That is the right answer to the failure mode the body itself names. Also corrects a real inaccuracy in an existing doc — memory-and-learning.md stated the decay table as if those history bodies reach the prompt. AGENTS.md router row added so a context.py change reaches the doc under the same-commit rule.

amadsalmon pushed a commit to amadsalmon/KiroCrew that referenced this pull request Sep 22, 2026
Answers six questions about what reaches the model, from current code:
the first-turn block order, the per-turn additions, a sub-agent's scope,
why a custom agent sees no skills, how a crew member's session is built,
and which crew-member private files exist today.

Cross-links agents/skills/subagents/memory docs and the module specs rather
than restating them. Citations name a file and a symbol, since docs-lint
rejects line numbers.

Co-authored-by: Joe Guo <zejiangg@amazon.com>
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.

3 participants