feat(3081): auto-trim review prompts for small-context model reviewers (#3708)
* feat(3081): auto-trim review prompts for small-context model reviewers Adds review.max_prompt_tokens and review.max_prompt_tokens_per_reviewer config keys. When configured, the /gsd-review workflow deterministically trims the assembled prompt before sending to each reviewer (drop CONTEXT → RESEARCH → REQUIREMENTS; head-shrink PROJECT.md; tail-truncate PLANs proportionally; reserve disclosure-note tokens upfront). Trim metadata is recorded in REVIEWS.md frontmatter. Reviewer is skipped with a warning if even the minimum review set exceeds the budget. Closes #3081 * fix(3081): register prompt-budget in SDK query registry and update inventory manifest review.md references `gsd-sdk query prompt-budget` at three call sites, but the command had no handler in the SDK registry — failing the registry-integration drift-guard test on all 6 CI matrix legs. Added a native TypeScript SDK handler (sdk/src/query/prompt-budget.ts) that ports the applyBudget logic from the CJS module, registered it in DOMAIN_STATIC_CATALOG, and regenerated docs/INVENTORY-MANIFEST.json to include the new cli_modules/prompt-budget.cjs entry. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(3081): bump ws to 8.20.1 and allowlist prompt-budget sibling pair Two additional CI failures after the registry fix: 1. ws moderate CVE (GHSA-58qx-3vcg-4xpx, uninitialized memory disclosure): The advisory covers ws >=8.0.0 <8.20.1. Both root and sdk/package.json pinned ^8.20.0 which resolved to 8.20.0. Bumped both to 8.20.1 to clear the npm audit drift-guard test (bug-3588-npm-audit-clean.test.cjs). 2. lint-shared-module-handsync detected the new prompt-budget.ts / prompt-budget.cjs sibling pair without an allowlist entry. Added a cooperatingSiblings entry to scripts/shared-module-handsync-allowlist.json with classification and justification matching the established pattern. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(3081): align prompt-budget skip semantics across CJS and SDK dispatch paths Replace brittle `[ $EXIT -eq 2 ]` guards with `[ $EXIT -ne 0 ]` in all three local-reviewer blocks (Ollama, LM Studio, llama.cpp) in workflows/review.md. Any non-zero exit from prompt-budget now triggers a skip with a descriptive warning — exit 2/11 prints "budget too small", any other non-zero prints "unexpected exit code". This ensures the SDK bridge dispatch path (exit 11 via GSDError(Blocked)) triggers the same skip as the CJS path (exit 2). The SDK handler (sdk/src/query/prompt-budget.ts) already writes both metadata and prompt files before throwing, so no change needed there. The Ollama block also gains the missing OLLAMA_SKIP guard so the reviewer invocation is actually skipped (previously the block only suppressed the OLLAMA_PROMPT_FILE update but still ran the curl invocation). SDK integration path (hardFailed via GSDError(Blocked) → exit 11) is covered by handler unit tests in tests/prompt-budget.test.cjs; no gsd-sdk-*.test.cjs exercising the full bridge dispatch for this command exists yet — that gap remains and is documented here. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix prompt-budget trim ordering and review guard follow-ups * perf: optimize prompt-budget and dedup reviewer trim workflow * fix(3708): drop source-grep theater tests to satisfy lint-no-source-grep All four test files added in commit 2df566ed were pure source-grep theater: they read .cjs / .ts / .md source files and asserted that specific string literals were present or absent. None exercised runtime behaviour. Deleted: - tests/gsd-tools-memory-optimizer.test.cjs — 7 includes() on gsd-tools.cjs - tests/prompt-budget-hotpath-optimizer.test.cjs — includes() on prompt-budget.cjs + .ts - tests/prompt-budget-io-optimizer.test.cjs — includes() on prompt-budget.ts + gsd-tools.cjs - tests/review-workflow-budget-dedup.test.cjs — includes() on review.md Behavioural coverage for the prompt-budget feature already exists in tests/prompt-budget.test.cjs and tests/prompt-budget-cli.test.cjs (also added by this PR). No replacement tests needed. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * fix(3708): correct budget-pressure threshold and minSet accounting Two bugs in applyBudget caused premature trimming and false hard-fails: 1. UNNEEDED_TRIM: budgetUnderPressure compared baseTokens against effectiveBudget - NOTE_RESERVE_TOKENS, triggering trim pressure 80 tokens before the budget was actually exceeded. Fix: compare against effectiveBudget directly; NOTE_RESERVE_TOKENS are still reserved in contentBudget once real pressure is confirmed. 2. FALSE_HARDFAIL: minSet included NOTE_RESERVE_TOKENS unconditionally, treating the note as mandatory even when no trim would occur and no note would be injected. Fix: exclude NOTE_RESERVE_TOKENS from minSet; a prompt that fits untrimmed needs no note and must not hard-fail. Both fixes applied in CJS and TypeScript implementations. Two regression tests added (cycles 11 and 12) that reproduce each case behaviorally. --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
@@ -21,6 +21,7 @@ import { uatRenderCheckpoint, auditUat } from './uat.js';
|
||||
import { writeProfile, generateClaudeProfile, generateDevPreferences, generateClaudeMd } from './profile-output.js';
|
||||
import { phaseMvpMode, taskIsBehaviorAdding, userStoryValidate } from './mvp.js';
|
||||
import { worktreeCleanupWave } from './worktree.js';
|
||||
import { promptBudget } from './prompt-budget.js';
|
||||
|
||||
export const DOMAIN_STATIC_CATALOG: ReadonlyArray<readonly [string, QueryHandler]> = [
|
||||
['agent-skills', agentSkills],
|
||||
@@ -104,4 +105,5 @@ export const DOMAIN_STATIC_CATALOG: ReadonlyArray<readonly [string, QueryHandler
|
||||
['task is-behavior-adding', taskIsBehaviorAdding],
|
||||
['user-story.validate', userStoryValidate],
|
||||
['user-story validate', userStoryValidate],
|
||||
['prompt-budget', promptBudget],
|
||||
] as const;
|
||||
|
||||
556
sdk/src/query/prompt-budget.ts
Normal file
556
sdk/src/query/prompt-budget.ts
Normal file
@@ -0,0 +1,556 @@
|
||||
'use strict';
|
||||
|
||||
/**
|
||||
* prompt-budget — SDK handler for applying a token budget to review prompts.
|
||||
*
|
||||
* Port of get-shit-done/bin/lib/prompt-budget.cjs + the `case 'prompt-budget':`
|
||||
* block in get-shit-done/bin/gsd-tools.cjs.
|
||||
*
|
||||
* CLI call surface (via `gsd-sdk query prompt-budget`):
|
||||
* --budget <N> Token budget (required, positive integer)
|
||||
* --instructions-file <path> Path to instructions file (required)
|
||||
* --roadmap-file <path> Path to roadmap file (required)
|
||||
* --plan-file <path> Path to a plan file (required, repeatable)
|
||||
* --output-prompt <path> Path to write the trimmed prompt (required)
|
||||
* --output-metadata <path> Path to write the JSON metadata (required)
|
||||
* --project-file <path> Optional PROJECT.md file
|
||||
* --context-file <path> Optional context file
|
||||
* --research-file <path> Optional research file
|
||||
* --requirements-file <path> Optional requirements file
|
||||
* --safety-margin-pct <N> Safety margin % (default 10)
|
||||
* --project-md-head-lines <N> Max lines from PROJECT.md (default 40)
|
||||
*
|
||||
* Exit codes (propagated through dispatch error):
|
||||
* 0 success (trim or no-trim)
|
||||
* 1 invocation error (missing required arg, missing file, invalid budget)
|
||||
* 2 hardFailed: prompt cannot fit effective budget after trim policy
|
||||
*/
|
||||
|
||||
import { readFile, writeFile } from 'node:fs/promises';
|
||||
import { basename, resolve } from 'node:path';
|
||||
import { GSDError, ErrorClassification } from '../errors.js';
|
||||
import type { QueryHandler } from './utils.js';
|
||||
|
||||
// ─── Constants ───────────────────────────────────────────────────────────────
|
||||
|
||||
const NOTE_RESERVE_TOKENS = 80;
|
||||
|
||||
const DEFAULT_NOTE_TEMPLATE = [
|
||||
'<note>',
|
||||
'Prompt automatically trimmed to fit a {budget}-token budget.',
|
||||
'Omitted sections: {omittedList}.',
|
||||
'Plan content truncated by approximately {planTruncationPct}%.',
|
||||
'Treat any missing context as out-of-scope rather than a review concern.',
|
||||
'</note>',
|
||||
].join('\n');
|
||||
|
||||
// ─── Pure helpers ─────────────────────────────────────────────────────────────
|
||||
|
||||
function estimateTokens(text: string): number {
|
||||
if (!text) return 0;
|
||||
return Math.ceil(text.length / 4);
|
||||
}
|
||||
|
||||
function renderNote(
|
||||
template: string,
|
||||
budget: number,
|
||||
omitted: string[],
|
||||
planTruncationPct: number,
|
||||
): string {
|
||||
const omittedList = omitted.length > 0 ? omitted.join(', ') : 'none';
|
||||
return template
|
||||
.replace('{budget}', String(budget))
|
||||
.replace('{omittedList}', omittedList)
|
||||
.replace('{planTruncationPct}', String(Math.round(planTruncationPct)));
|
||||
}
|
||||
|
||||
function headShrink(text: string, maxLines: number): string {
|
||||
if (maxLines <= 0) return '';
|
||||
let idx = -1;
|
||||
let seen = 0;
|
||||
while (seen < maxLines) {
|
||||
idx = text.indexOf('\n', idx + 1);
|
||||
if (idx === -1) return text;
|
||||
seen += 1;
|
||||
}
|
||||
return text.slice(0, idx);
|
||||
}
|
||||
|
||||
function tailTruncate(text: string, maxChars: number): string {
|
||||
if (text.length <= maxChars) return text;
|
||||
return text.slice(0, maxChars);
|
||||
}
|
||||
|
||||
interface PlanEntry {
|
||||
file: string;
|
||||
content: string;
|
||||
}
|
||||
|
||||
interface BudgetSections {
|
||||
instructions: string;
|
||||
roadmap: string;
|
||||
plans: PlanEntry[];
|
||||
projectMd: string | null;
|
||||
context: string | null;
|
||||
research: string | null;
|
||||
requirements: string | null;
|
||||
}
|
||||
|
||||
interface BudgetOptions {
|
||||
safetyMarginPct?: number;
|
||||
noteTemplate?: string;
|
||||
projectMdHeadLines?: number;
|
||||
}
|
||||
|
||||
interface BudgetMetadata {
|
||||
budget: number;
|
||||
effectiveBudget: number;
|
||||
estimatedTokens: number;
|
||||
omitted: string[];
|
||||
projectMdShrunk: boolean;
|
||||
planTruncationPct: number;
|
||||
hardFailed: boolean;
|
||||
noteInjected: boolean;
|
||||
}
|
||||
|
||||
interface BudgetResult {
|
||||
prompt: string;
|
||||
metadata: BudgetMetadata;
|
||||
}
|
||||
|
||||
function assemblePrompt(parts: {
|
||||
instructions: string;
|
||||
note: string | null;
|
||||
roadmap: string;
|
||||
projectMd: string | null;
|
||||
plans: PlanEntry[];
|
||||
context: string | null;
|
||||
research: string | null;
|
||||
requirements: string | null;
|
||||
}): string {
|
||||
const blocks: string[] = [];
|
||||
|
||||
blocks.push(parts.instructions);
|
||||
|
||||
if (parts.note) blocks.push(parts.note);
|
||||
|
||||
blocks.push('## Roadmap\n\n' + parts.roadmap);
|
||||
|
||||
if (parts.projectMd) blocks.push('## Project\n\n' + parts.projectMd);
|
||||
|
||||
const planBlocks = parts.plans
|
||||
.map((p) => '### ' + p.file + '\n\n' + p.content)
|
||||
.join('\n\n');
|
||||
blocks.push('## Plans\n\n' + planBlocks);
|
||||
|
||||
if (parts.context) blocks.push('## Context\n\n' + parts.context);
|
||||
if (parts.research) blocks.push('## Research\n\n' + parts.research);
|
||||
if (parts.requirements) blocks.push('## Requirements\n\n' + parts.requirements);
|
||||
|
||||
return blocks.join('\n\n');
|
||||
}
|
||||
|
||||
function applyBudget({
|
||||
sections,
|
||||
budget,
|
||||
options = {},
|
||||
}: {
|
||||
sections: BudgetSections;
|
||||
budget: number;
|
||||
options?: BudgetOptions;
|
||||
}): BudgetResult {
|
||||
const {
|
||||
safetyMarginPct = 10,
|
||||
noteTemplate = DEFAULT_NOTE_TEMPLATE,
|
||||
projectMdHeadLines = 40,
|
||||
} = options;
|
||||
|
||||
const effectiveBudget = Math.floor(budget * (1 - safetyMarginPct / 100));
|
||||
|
||||
const {
|
||||
instructions,
|
||||
roadmap,
|
||||
plans,
|
||||
projectMd: projectMdRaw = null,
|
||||
context: contextRaw = null,
|
||||
research: researchRaw = null,
|
||||
requirements: requirementsRaw = null,
|
||||
} = sections;
|
||||
|
||||
let projectMd = projectMdRaw;
|
||||
let context = contextRaw;
|
||||
let research = researchRaw;
|
||||
let requirements = requirementsRaw;
|
||||
let workingPlans: PlanEntry[] = plans.map((p) => ({ file: p.file, content: p.content }));
|
||||
|
||||
const omitted: string[] = [];
|
||||
let projectMdShrunk = false;
|
||||
let planTruncationPct = 0;
|
||||
let noteInjected = false;
|
||||
let hardFailed = false;
|
||||
|
||||
// Minimum-set check: instructions + roadmap + 1KB per plan.
|
||||
// NOTE_RESERVE_TOKENS is intentionally excluded here: a note is only injected
|
||||
// when trimming actually occurs, and a prompt that fits without any trim needs
|
||||
// no note at all. Including NOTE_RESERVE_TOKENS here would cause false hard-fails
|
||||
// for prompts that genuinely fit the effective budget untrimmed.
|
||||
const MIN_PLAN_BYTES = 1024;
|
||||
const minPlanTokens = plans.reduce((sum, p) => {
|
||||
return sum + estimateTokens(p.content.slice(0, MIN_PLAN_BYTES));
|
||||
}, 0);
|
||||
const minSet =
|
||||
estimateTokens(instructions) +
|
||||
estimateTokens(roadmap) +
|
||||
minPlanTokens;
|
||||
|
||||
if (minSet > effectiveBudget) {
|
||||
return {
|
||||
prompt: '',
|
||||
metadata: {
|
||||
budget,
|
||||
effectiveBudget,
|
||||
estimatedTokens: 0,
|
||||
omitted: [],
|
||||
projectMdShrunk: false,
|
||||
planTruncationPct: 0,
|
||||
hardFailed: true,
|
||||
noteInjected: false,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
const TOKENS_ROADMAP_HEADER = estimateTokens('## Roadmap\n\n');
|
||||
const TOKENS_PROJECT_HEADER = estimateTokens('## Project\n\n');
|
||||
const TOKENS_PLANS_HEADER = estimateTokens('## Plans\n\n');
|
||||
const TOKENS_CONTEXT_HEADER = estimateTokens('## Context\n\n');
|
||||
const TOKENS_RESEARCH_HEADER = estimateTokens('## Research\n\n');
|
||||
const TOKENS_REQUIREMENTS_HEADER = estimateTokens('## Requirements\n\n');
|
||||
const TOKENS_PLAN_ITEM_HEADERS = workingPlans.reduce(
|
||||
(sum, p) => sum + estimateTokens('### ' + p.file + '\n\n'),
|
||||
0,
|
||||
);
|
||||
|
||||
const staticBaseTokens =
|
||||
estimateTokens(instructions) +
|
||||
TOKENS_ROADMAP_HEADER +
|
||||
estimateTokens(roadmap) +
|
||||
TOKENS_PLANS_HEADER +
|
||||
TOKENS_PLAN_ITEM_HEADERS;
|
||||
|
||||
let projectTokens = projectMd ? TOKENS_PROJECT_HEADER + estimateTokens(projectMd) : 0;
|
||||
let contextTokens = context ? TOKENS_CONTEXT_HEADER + estimateTokens(context) : 0;
|
||||
let researchTokens = research ? TOKENS_RESEARCH_HEADER + estimateTokens(research) : 0;
|
||||
let requirementsTokens = requirements ? TOKENS_REQUIREMENTS_HEADER + estimateTokens(requirements) : 0;
|
||||
let planContentTokens = workingPlans.reduce((sum, p) => sum + estimateTokens(p.content), 0);
|
||||
|
||||
const getCurrentBaseTokens = (): number =>
|
||||
staticBaseTokens +
|
||||
projectTokens +
|
||||
planContentTokens +
|
||||
contextTokens +
|
||||
researchTokens +
|
||||
requirementsTokens;
|
||||
|
||||
let currentBaseTokens = getCurrentBaseTokens();
|
||||
|
||||
// Detect budget pressure: is ANY trim needed?
|
||||
// Pressure exists when the current base tokens already exceed the effective
|
||||
// budget. Only when pressure is real do we reserve NOTE_RESERVE_TOKENS so
|
||||
// the note itself fits after trimming. Checking against
|
||||
// effectiveBudget - NOTE_RESERVE_TOKENS (the old threshold) would cause
|
||||
// spurious pressure 80 tokens early, dropping sections that fit fine.
|
||||
const baseTokens = currentBaseTokens;
|
||||
const budgetUnderPressure = baseTokens > effectiveBudget;
|
||||
let contentBudget = budgetUnderPressure ? effectiveBudget - NOTE_RESERVE_TOKENS : effectiveBudget;
|
||||
|
||||
// Trim step 1: head-shrink PROJECT.md
|
||||
if (currentBaseTokens > contentBudget && projectMd) {
|
||||
const shrunk = headShrink(projectMd, projectMdHeadLines);
|
||||
if (shrunk !== projectMd) {
|
||||
projectMd = shrunk;
|
||||
projectMdShrunk = true;
|
||||
projectTokens = TOKENS_PROJECT_HEADER + estimateTokens(projectMd);
|
||||
currentBaseTokens = getCurrentBaseTokens();
|
||||
}
|
||||
}
|
||||
|
||||
// Trim step 2: proportional plan truncation
|
||||
if (currentBaseTokens > contentBudget) {
|
||||
const overhead =
|
||||
staticBaseTokens +
|
||||
projectTokens +
|
||||
contextTokens +
|
||||
researchTokens +
|
||||
requirementsTokens;
|
||||
|
||||
const planBudgetTokens = contentBudget - overhead;
|
||||
const totalPlanTokens = planContentTokens;
|
||||
|
||||
if (planBudgetTokens > 0 && planBudgetTokens < totalPlanTokens) {
|
||||
const totalOriginalChars = plans.reduce((sum, p) => sum + p.content.length, 0);
|
||||
|
||||
workingPlans = workingPlans.map((p) => {
|
||||
const proportionalShare =
|
||||
totalOriginalChars > 0
|
||||
? Math.floor((p.content.length / totalOriginalChars) * (planBudgetTokens * 4))
|
||||
: 0;
|
||||
const maxChars = Math.max(proportionalShare, MIN_PLAN_BYTES);
|
||||
return { file: p.file, content: tailTruncate(p.content, maxChars) };
|
||||
});
|
||||
|
||||
const newTotalChars = workingPlans.reduce((sum, p) => sum + p.content.length, 0);
|
||||
if (totalOriginalChars > 0) {
|
||||
planTruncationPct = ((totalOriginalChars - newTotalChars) / totalOriginalChars) * 100;
|
||||
}
|
||||
planContentTokens = workingPlans.reduce((sum, p) => sum + estimateTokens(p.content), 0);
|
||||
currentBaseTokens = getCurrentBaseTokens();
|
||||
}
|
||||
}
|
||||
|
||||
// Trim step 3: drop context
|
||||
if (currentBaseTokens > contentBudget && context) {
|
||||
context = null;
|
||||
omitted.push('context');
|
||||
contextTokens = 0;
|
||||
currentBaseTokens = getCurrentBaseTokens();
|
||||
}
|
||||
|
||||
// Trim step 4: drop research
|
||||
if (currentBaseTokens > contentBudget && research) {
|
||||
research = null;
|
||||
omitted.push('research');
|
||||
researchTokens = 0;
|
||||
currentBaseTokens = getCurrentBaseTokens();
|
||||
}
|
||||
|
||||
// Trim step 5: drop requirements (last resort)
|
||||
if (currentBaseTokens > contentBudget && requirements) {
|
||||
requirements = null;
|
||||
omitted.push('requirements');
|
||||
requirementsTokens = 0;
|
||||
currentBaseTokens = getCurrentBaseTokens();
|
||||
}
|
||||
|
||||
const anyTrimOccurred = omitted.length > 0 || projectMdShrunk || planTruncationPct > 0;
|
||||
|
||||
let note: string | null = null;
|
||||
if (anyTrimOccurred) {
|
||||
note = renderNote(noteTemplate, budget, omitted, planTruncationPct);
|
||||
noteInjected = true;
|
||||
}
|
||||
|
||||
const prompt = assemblePrompt({
|
||||
instructions,
|
||||
note,
|
||||
roadmap,
|
||||
projectMd,
|
||||
plans: workingPlans,
|
||||
context,
|
||||
research,
|
||||
requirements,
|
||||
});
|
||||
|
||||
const estimatedTokens = estimateTokens(prompt);
|
||||
|
||||
if (estimatedTokens > effectiveBudget) {
|
||||
hardFailed = true;
|
||||
return {
|
||||
prompt: '',
|
||||
metadata: {
|
||||
budget,
|
||||
effectiveBudget,
|
||||
estimatedTokens,
|
||||
omitted,
|
||||
projectMdShrunk,
|
||||
planTruncationPct,
|
||||
hardFailed,
|
||||
noteInjected,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
prompt,
|
||||
metadata: {
|
||||
budget,
|
||||
effectiveBudget,
|
||||
estimatedTokens,
|
||||
omitted,
|
||||
projectMdShrunk,
|
||||
planTruncationPct,
|
||||
hardFailed,
|
||||
noteInjected,
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
// ─── CLI arg helpers ──────────────────────────────────────────────────────────
|
||||
|
||||
function getFlag(args: string[], flag: string): string | null {
|
||||
const idx = args.indexOf(flag);
|
||||
if (idx === -1) return null;
|
||||
const val = args[idx + 1];
|
||||
if (val === undefined || val.startsWith('--')) return null;
|
||||
return val;
|
||||
}
|
||||
|
||||
function getPlanFiles(args: string[]): string[] {
|
||||
const planFiles: string[] = [];
|
||||
for (let i = 0; i < args.length; i++) {
|
||||
if (args[i] === '--plan-file' && args[i + 1] && !args[i + 1].startsWith('--')) {
|
||||
planFiles.push(args[i + 1]);
|
||||
i++;
|
||||
}
|
||||
}
|
||||
return planFiles;
|
||||
}
|
||||
|
||||
async function readRequired(filePath: string, flagName: string): Promise<string> {
|
||||
const resolved = resolve(filePath);
|
||||
try {
|
||||
return await readFile(resolved, 'utf8');
|
||||
} catch (err) {
|
||||
const msg = err && typeof err === 'object' && 'code' in err && err.code === 'ENOENT'
|
||||
? `file not found for ${flagName}: ${resolved}`
|
||||
: `cannot read ${flagName}: ${resolved}`;
|
||||
throw new GSDError(
|
||||
msg,
|
||||
ErrorClassification.Validation,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
async function readOptional(filePath: string | null): Promise<string | null> {
|
||||
if (!filePath) return null;
|
||||
const resolved = resolve(filePath);
|
||||
try {
|
||||
return await readFile(resolved, 'utf8');
|
||||
} catch (err) {
|
||||
if (err && typeof err === 'object' && 'code' in err && err.code === 'ENOENT') {
|
||||
return null;
|
||||
}
|
||||
throw err;
|
||||
}
|
||||
}
|
||||
|
||||
// ─── Handler ─────────────────────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* SDK handler for `gsd-sdk query prompt-budget`.
|
||||
*
|
||||
* Reads input files, applies the token budget algorithm, writes the trimmed
|
||||
* prompt and metadata to the specified output files, and returns the metadata.
|
||||
*
|
||||
* Throws `GSDError(Validation)` on missing required args or missing files.
|
||||
* Throws `GSDError(Blocked)` when the minimum-set exceeds the effective budget
|
||||
* (hard-fail, exit code 11 — callers that previously relied on exit code 2 from
|
||||
* the CJS fallback path should treat any non-zero exit as "skip reviewer").
|
||||
*/
|
||||
export const promptBudget: QueryHandler = async (args, _projectDir) => {
|
||||
// Collect multi-value --plan-file flags
|
||||
const planFilePaths = getPlanFiles(args);
|
||||
|
||||
// Parse single-value flags
|
||||
const budgetStr = getFlag(args, '--budget');
|
||||
const instructionsFile = getFlag(args, '--instructions-file');
|
||||
const roadmapFile = getFlag(args, '--roadmap-file');
|
||||
const outputPromptFile = getFlag(args, '--output-prompt');
|
||||
const outputMetadataFile = getFlag(args, '--output-metadata');
|
||||
const safetyMarginStr = getFlag(args, '--safety-margin-pct');
|
||||
const projectMdHeadLinesStr = getFlag(args, '--project-md-head-lines');
|
||||
const projectFile = getFlag(args, '--project-file');
|
||||
const contextFile = getFlag(args, '--context-file');
|
||||
const researchFile = getFlag(args, '--research-file');
|
||||
const requirementsFile = getFlag(args, '--requirements-file');
|
||||
|
||||
// Validate required args
|
||||
if (!budgetStr) {
|
||||
throw new GSDError('--budget <N> is required', ErrorClassification.Validation);
|
||||
}
|
||||
const budget = parseInt(budgetStr, 10);
|
||||
if (!Number.isFinite(budget) || budget <= 0) {
|
||||
throw new GSDError('--budget must be a positive integer', ErrorClassification.Validation);
|
||||
}
|
||||
if (!instructionsFile) {
|
||||
throw new GSDError('--instructions-file <path> is required', ErrorClassification.Validation);
|
||||
}
|
||||
if (!roadmapFile) {
|
||||
throw new GSDError('--roadmap-file <path> is required', ErrorClassification.Validation);
|
||||
}
|
||||
if (planFilePaths.length === 0) {
|
||||
throw new GSDError(
|
||||
'at least one --plan-file <path> is required',
|
||||
ErrorClassification.Validation,
|
||||
);
|
||||
}
|
||||
if (!outputPromptFile) {
|
||||
throw new GSDError('--output-prompt <path> is required', ErrorClassification.Validation);
|
||||
}
|
||||
if (!outputMetadataFile) {
|
||||
throw new GSDError('--output-metadata <path> is required', ErrorClassification.Validation);
|
||||
}
|
||||
|
||||
// Read input files
|
||||
const instructions = await readRequired(instructionsFile, '--instructions-file');
|
||||
const roadmap = await readRequired(roadmapFile, '--roadmap-file');
|
||||
const plans: PlanEntry[] = await Promise.all(planFilePaths.map(async (p) => {
|
||||
const resolved = resolve(p);
|
||||
try {
|
||||
const content = await readFile(resolved, 'utf8');
|
||||
return { file: basename(p), content };
|
||||
} catch (err) {
|
||||
if (err && typeof err === 'object' && 'code' in err && err.code === 'ENOENT') {
|
||||
throw new GSDError(
|
||||
`plan file not found: ${resolved}`,
|
||||
ErrorClassification.Validation,
|
||||
);
|
||||
}
|
||||
throw new GSDError(
|
||||
`cannot read plan file: ${resolved}`,
|
||||
ErrorClassification.Validation,
|
||||
);
|
||||
}
|
||||
}));
|
||||
|
||||
const projectMd = await readOptional(projectFile);
|
||||
const context = await readOptional(contextFile);
|
||||
const research = await readOptional(researchFile);
|
||||
const requirements = await readOptional(requirementsFile);
|
||||
|
||||
// Build options
|
||||
const options: BudgetOptions = {};
|
||||
if (safetyMarginStr !== null) {
|
||||
const pct = parseInt(safetyMarginStr, 10);
|
||||
if (Number.isFinite(pct)) options.safetyMarginPct = pct;
|
||||
}
|
||||
if (projectMdHeadLinesStr !== null) {
|
||||
const lines = parseInt(projectMdHeadLinesStr, 10);
|
||||
if (Number.isFinite(lines)) options.projectMdHeadLines = lines;
|
||||
}
|
||||
|
||||
// Apply budget
|
||||
const sections: BudgetSections = {
|
||||
instructions,
|
||||
roadmap,
|
||||
plans,
|
||||
projectMd,
|
||||
context,
|
||||
research,
|
||||
requirements,
|
||||
};
|
||||
const { prompt, metadata } = applyBudget({ sections, budget, options });
|
||||
|
||||
// Write outputs (always write metadata; prompt may be empty on hard-fail)
|
||||
await writeFile(resolve(outputMetadataFile), JSON.stringify(metadata, null, 2));
|
||||
await writeFile(resolve(outputPromptFile), prompt);
|
||||
|
||||
// Signal hard-fail
|
||||
if (metadata.hardFailed) {
|
||||
throw new GSDError(
|
||||
'prompt-budget hard failed: minimum-set exceeds the effective budget',
|
||||
ErrorClassification.Blocked,
|
||||
);
|
||||
}
|
||||
|
||||
return { data: metadata };
|
||||
};
|
||||
Reference in New Issue
Block a user