kebab/tasks/p9/p9-fb-34-output-budget-controls.md

phase, component, task_id, title, status, target_version, depends_on, unblocks, contract_source, contract_sections, source_feedback

phase	component	task_id	title	status	target_version	depends_on	unblocks	contract_source	contract_sections	source_feedback
P9	kebab-cli + kebab-app + wire-schema	p9-fb-34	Output budget controls (--max-tokens / --snippet-chars / pagination)	completed	0.5.0			../../docs/superpowers/specs/2026-04-27-kebab-final-form-design.md	§4 search §10 UX wire-schema search_hit.v1	사용자 도그푸딩 2026-05-06 — agent context window 제한적. 검색 결과 양 / snippet 길이 / 페이지네이션 control 필요.

p9-fb-34 — Output budget controls

✅ 구현 완료. 본 spec 은 구현 시점의 frozen 상태. post-merge deviation 은 HOTFIXES.md 의 2026-05-09 — p9-fb-34 항목 참조 — live source of truth.

상세 설계: docs/superpowers/specs/2026-05-09-p9-fb-34-output-budget-controls-design.md. 구현 계획: docs/superpowers/plans/2026-05-09-p9-fb-34-output-budget-controls.md.

증상 / 동기

• agent context window 한정 — 검색 결과 5KB 이하로 받고 싶을 때 control 없음.
• snippet 길이 고정 → narrow context 에서 한 hit 만 받아도 차고 넘침.
• top-5 본 후 추가 5 보고 싶을 때 페이지네이션 없음.

Goal (skeleton)

• kebab search --max-tokens N — 결과 직렬화 size 가 N tokens 안에 들도록 truncate / k 자동 축소.
• kebab search --snippet-chars N — 각 hit 의 snippet 최대 chars.
• kebab search --cursor <opaque> — 이전 호출의 cursor 로 다음 페이지.
• response 에 next_cursor 필드 (남은 hit 있을 때).

후속 작업 — brainstorm 필요 항목

• token 카운트 — tiktoken 류 dependency vs 단순 byte/4 근사.
• truncate 우선순위 — snippet 단축 → k 축소 → metadata 제거.
• cursor 의 안정성 — index 변경 후 cursor 유효성.
• kebab ask 도 동일 인자 (--max-tokens 결과 답변 길이 제한)?

Risks / notes

• wire schema additive — next_cursor 필드 추가 minor.
• agent UX — truncate 발생 시 명시적 hint (truncated: true) 필요.
• 기본값 — agent 친화 (작은 budget) vs 사람 친화 (큰 budget) trade-off.