prjct-cli 1.9.0 → 1.11.0

package/core/agentic/token-budget.ts

@@ -0,0 +1,226 @@
+/**
+ * Token Budget Coordinator
+ *
+ * Centrally manages the global token budget across all context-loading components.
+ * Ensures the combined prompt stays within the model's context window
+ * and reserves space for the output.
+ *
+ * Budget formula: inputBudget = modelContextWindow * 0.65
+ * Priority: state (P1) > injection context (P2) > file content (P3)
+ *
+ * @see PRJ-266
+ */
+
+// =============================================================================
+// Model Context Windows
+// =============================================================================
+
+/** Context window sizes by model identifier (in tokens) */
+export const MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  // Claude models (short names from model.ts)
+  opus: 200_000,
+  sonnet: 200_000,
+  haiku: 200_000,
+  // Gemini models
+  '2.5-pro': 1_000_000,
+  '2.5-flash': 1_000_000,
+  '2.0-flash': 1_000_000,
+  // Full model IDs (for direct API usage)
+  'claude-opus-4.5': 200_000,
+  'claude-sonnet-4.5': 200_000,
+  'claude-haiku-4.5': 200_000,
+  'claude-opus-4-6': 200_000,
+  // Default fallback
+  default: 200_000,
+}
+
+/** Ratio of context window reserved for input (rest for output) */
+export const INPUT_RATIO = 0.65
+
+// =============================================================================
+// Budget Categories
+// =============================================================================
+
+/** Budget category identifiers ordered by priority */
+export type BudgetCategory = 'state' | 'injection' | 'files'
+
+/** Budget allocation result for each category */
+export interface BudgetAllocation {
+  state: number
+  injection: number
+  files: number
+  inputBudget: number
+  outputReserve: number
+  contextWindow: number
+}
+
+/** Usage tracking per category */
+export interface BudgetUsage {
+  category: BudgetCategory
+  allocated: number
+  used: number
+  remaining: number
+}
+
+// =============================================================================
+// Default Allocation Ratios (within input budget)
+// =============================================================================
+
+interface AllocationConfig {
+  ratio: number
+  minimum: number
+}
+
+const ALLOCATION_CONFIG: Record<BudgetCategory, AllocationConfig> = {
+  /** P1: State — current task, queue, patterns (highest priority) */
+  state: { ratio: 0.02, minimum: 1_500 },
+  /** P2: Injection — agents, skills, modules, checklists */
+  injection: { ratio: 0.08, minimum: 8_000 },
+  /** P3: Files — codebase file content (lowest priority, gets remainder) */
+  files: { ratio: 0.9, minimum: 20_000 },
+}
+
+/** Priority order for budget distribution */
+const PRIORITY_ORDER: BudgetCategory[] = ['state', 'injection', 'files']
+
+// =============================================================================
+// TokenBudgetCoordinator
+// =============================================================================
+
+export class TokenBudgetCoordinator {
+  private readonly _contextWindow: number
+  private readonly _inputBudget: number
+  private readonly _outputReserve: number
+  private readonly _allocations: Map<BudgetCategory, number> = new Map()
+  private readonly _used: Map<BudgetCategory, number> = new Map()
+
+  constructor(model?: string) {
+    this._contextWindow = getContextWindow(model)
+    this._inputBudget = Math.floor(this._contextWindow * INPUT_RATIO)
+    this._outputReserve = this._contextWindow - this._inputBudget
+    this.distributeBudget()
+  }
+
+  /** Distribute input budget across categories by priority */
+  private distributeBudget(): void {
+    let remaining = this._inputBudget
+
+    for (const category of PRIORITY_ORDER) {
+      const config = ALLOCATION_CONFIG[category]
+
+      if (category === 'files') {
+        // Lowest priority gets whatever remains
+        this._allocations.set(category, Math.max(remaining, 0))
+      } else {
+        const allocation = Math.max(config.minimum, Math.floor(this._inputBudget * config.ratio))
+        const granted = Math.min(allocation, remaining)
+        this._allocations.set(category, granted)
+        remaining -= granted
+      }
+
+      this._used.set(category, 0)
+    }
+  }
+
+  /** Get the full budget allocation */
+  getAllocation(): BudgetAllocation {
+    return {
+      state: this._allocations.get('state') ?? 0,
+      injection: this._allocations.get('injection') ?? 0,
+      files: this._allocations.get('files') ?? 0,
+      inputBudget: this._inputBudget,
+      outputReserve: this._outputReserve,
+      contextWindow: this._contextWindow,
+    }
+  }
+
+  /**
+   * Request tokens from a category.
+   * Returns actual tokens granted (may be less than requested if budget is exhausted).
+   */
+  request(category: BudgetCategory, requestedTokens: number): number {
+    const allocated = this._allocations.get(category) ?? 0
+    const currentUsed = this._used.get(category) ?? 0
+    const available = Math.max(0, allocated - currentUsed)
+    const granted = Math.min(requestedTokens, available)
+    this._used.set(category, currentUsed + granted)
+    return granted
+  }
+
+  /** Record token usage for a category */
+  record(category: BudgetCategory, tokensUsed: number): void {
+    const current = this._used.get(category) ?? 0
+    this._used.set(category, current + tokensUsed)
+  }
+
+  /** Get usage details for a category */
+  getUsage(category: BudgetCategory): BudgetUsage {
+    const allocated = this._allocations.get(category) ?? 0
+    const used = this._used.get(category) ?? 0
+    return {
+      category,
+      allocated,
+      used,
+      remaining: Math.max(0, allocated - used),
+    }
+  }
+
+  /** Get allocation for a specific category */
+  getAllocationFor(category: BudgetCategory): number {
+    return this._allocations.get(category) ?? 0
+  }
+
+  /** Get total remaining input budget across all categories */
+  get totalRemaining(): number {
+    let totalUsed = 0
+    for (const v of this._used.values()) {
+      totalUsed += v
+    }
+    return Math.max(0, this._inputBudget - totalUsed)
+  }
+
+  /** Check if total usage exceeds input budget */
+  get isOverBudget(): boolean {
+    let totalUsed = 0
+    for (const v of this._used.values()) {
+      totalUsed += v
+    }
+    return totalUsed > this._inputBudget
+  }
+
+  /** Context window size */
+  get contextWindow(): number {
+    return this._contextWindow
+  }
+
+  /** Total input budget */
+  get inputBudget(): number {
+    return this._inputBudget
+  }
+
+  /** Output token reserve */
+  get outputReserve(): number {
+    return this._outputReserve
+  }
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/** Get context window size for a model identifier */
+export function getContextWindow(model?: string): number {
+  if (!model) return MODEL_CONTEXT_WINDOWS.default
+  return MODEL_CONTEXT_WINDOWS[model] ?? MODEL_CONTEXT_WINDOWS.default
+}
+
+/** Calculate input budget for a model */
+export function calculateInputBudget(model?: string): number {
+  return Math.floor(getContextWindow(model) * INPUT_RATIO)
+}
+
+/** Calculate output reserve for a model */
+export function calculateOutputReserve(model?: string): number {
+  const contextWindow = getContextWindow(model)
+  return contextWindow - Math.floor(contextWindow * INPUT_RATIO)
+}

package/core/commands/analysis.ts

@@ -12,6 +12,7 @@ import commandInstaller from '../infrastructure/command-installer'
 import { formatCost } from '../schemas/metrics'
 import { createStalenessChecker, memoryService, syncService } from '../services'
 import { formatDiffPreview, formatFullDiff, generateSyncDiff } from '../services/diff-generator'
+import { analysisStorage } from '../storage/analysis-storage'
 import { metricsStorage } from '../storage/metrics-storage'
 import type { AnalyzeOptions, CommandResult, ProjectContext } from '../types'
 import { getErrorMessage } from '../types/fs'
@@ -805,6 +806,9 @@ export class AnalysisCommands extends PrjctCommandsBase {
       // Get session info
       const sessionInfo = await checker.getSessionInfo(projectId)
 
+      // Get analysis status (PRJ-263)
+      const analysisStatus = await analysisStorage.getStatus(projectId)
+
       // JSON output mode
       if (options.json) {
         console.log(
@@ -812,9 +816,13 @@ export class AnalysisCommands extends PrjctCommandsBase {
             success: true,
             ...status,
             session: sessionInfo,
+            analysis: analysisStatus,
           })
         )
-        return { success: true, data: { ...status, session: sessionInfo } }
+        return {
+          success: true,
+          data: { ...status, session: sessionInfo, analysis: analysisStatus },
+        }
       }
 
       // Human-readable output
@@ -822,9 +830,22 @@ export class AnalysisCommands extends PrjctCommandsBase {
       console.log(checker.formatStatus(status))
       console.log('')
       console.log(checker.formatSessionInfo(sessionInfo))
+
+      // Show analysis status (PRJ-263)
+      if (analysisStatus.hasSealed || analysisStatus.hasDraft) {
+        console.log('')
+        console.log('Analysis:')
+        if (analysisStatus.hasSealed) {
+          console.log(`  Sealed: ${analysisStatus.sealedCommit} (${analysisStatus.sealedAt})`)
+        }
+        if (analysisStatus.hasDraft) {
+          console.log(`  Draft: ${analysisStatus.draftCommit} (pending seal)`)
+        }
+      }
+
       console.log('')
 
-      return { success: true, data: { ...status, session: sessionInfo } }
+      return { success: true, data: { ...status, session: sessionInfo, analysis: analysisStatus } }
     } catch (error) {
       const errMsg = getErrorMessage(error)
       if (options.json) {
@@ -836,6 +857,100 @@ export class AnalysisCommands extends PrjctCommandsBase {
     }
   }
 
+  /**
+   * prjct seal - Seal the current draft analysis (PRJ-263)
+   *
+   * Locks the current draft with a SHA-256 signature.
+   * Only sealed analysis feeds task context.
+   */
+  async seal(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean } = {}
+  ): Promise<CommandResult> {
+    try {
+      const initResult = await this.ensureProjectInit(projectPath)
+      if (!initResult.success) return initResult
+
+      const projectId = await configManager.getProjectId(projectPath)
+      if (!projectId) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: 'No project ID found' }))
+        }
+        return { success: false, error: 'No project ID found' }
+      }
+
+      const result = await analysisStorage.seal(projectId)
+
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            success: result.success,
+            signature: result.signature,
+            error: result.error,
+          })
+        )
+        return { success: result.success, error: result.error }
+      }
+
+      if (!result.success) {
+        out.fail(result.error || 'Seal failed')
+        return { success: false, error: result.error }
+      }
+
+      out.done('Analysis sealed')
+      console.log(`  Signature: ${result.signature?.substring(0, 16)}...`)
+      console.log('')
+
+      return { success: true, data: { signature: result.signature } }
+    } catch (error) {
+      const errMsg = getErrorMessage(error)
+      if (options.json) {
+        console.log(JSON.stringify({ success: false, error: errMsg }))
+      } else {
+        out.fail(errMsg)
+      }
+      return { success: false, error: errMsg }
+    }
+  }
+
+  /**
+   * prjct verify - Verify integrity of sealed analysis (PRJ-263)
+   */
+  async verify(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean } = {}
+  ): Promise<CommandResult> {
+    try {
+      const initResult = await this.ensureProjectInit(projectPath)
+      if (!initResult.success) return initResult
+
+      const projectId = await configManager.getProjectId(projectPath)
+      if (!projectId) {
+        return { success: false, error: 'No project ID found' }
+      }
+
+      const result = await analysisStorage.verify(projectId)
+
+      if (options.json) {
+        console.log(JSON.stringify(result))
+        return { success: result.valid }
+      }
+
+      if (result.valid) {
+        out.done(result.message)
+      } else {
+        out.fail(result.message)
+      }
+      console.log('')
+
+      return { success: result.valid, data: result }
+    } catch (error) {
+      const errMsg = getErrorMessage(error)
+      out.fail(errMsg)
+      return { success: false, error: errMsg }
+    }
+  }
+
   /**
    * Get session activity stats from today's events
    * @see PRJ-89

package/core/commands/command-data.ts

@@ -218,6 +218,35 @@ export const COMMANDS: CommandMeta[] = [
       'Configurable staleness thresholds',
     ],
   },
+  {
+    name: 'seal',
+    group: 'core',
+    description: 'Seal the current draft analysis with a commit-hash signature',
+    usage: { claude: '/p:seal', terminal: 'prjct seal' },
+    params: '[--json]',
+    implemented: true,
+    hasTemplate: false,
+    requiresProject: true,
+    features: [
+      'Locks draft analysis with SHA-256 signature',
+      'Only sealed analysis feeds task context',
+      'Detects staleness when HEAD moves past sealed commit',
+    ],
+  },
+  {
+    name: 'verify',
+    group: 'core',
+    description: 'Verify integrity of sealed analysis',
+    usage: { claude: '/p:verify', terminal: 'prjct verify' },
+    params: '[--json]',
+    implemented: true,
+    hasTemplate: false,
+    requiresProject: true,
+    features: [
+      'Recomputes SHA-256 signature and compares',
+      'Detects if sealed analysis was modified',
+    ],
+  },
   {
     name: 'help',
     group: 'core',

package/core/commands/commands.ts

@@ -218,6 +218,20 @@ class PrjctCommands {
     return this.analysis.status(projectPath, options)
   }
 
+  async seal(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean } = {}
+  ): Promise<CommandResult> {
+    return this.analysis.seal(projectPath, options)
+  }
+
+  async verify(
+    projectPath: string = process.cwd(),
+    options: { json?: boolean } = {}
+  ): Promise<CommandResult> {
+    return this.analysis.verify(projectPath, options)
+  }
+
   // ========== Context Commands ==========
 
   async context(

package/core/commands/register.ts

@@ -91,6 +91,8 @@ export function registerAllCommands(): void {
   commandRegistry.registerMethod('sync', analysis, 'sync', getMeta('sync'))
   commandRegistry.registerMethod('stats', analysis, 'stats', getMeta('stats'))
   commandRegistry.registerMethod('status', analysis, 'status', getMeta('status'))
+  commandRegistry.registerMethod('seal', analysis, 'seal', getMeta('seal'))
+  commandRegistry.registerMethod('verify', analysis, 'verify', getMeta('verify'))
 
   // Setup commands
   commandRegistry.registerMethod('start', setup, 'start', getMeta('start'))

package/core/index.ts

@@ -170,6 +170,8 @@ async function main(): Promise<void> {
             json: options.json === true,
             package: options.package ? String(options.package) : undefined,
           }),
+        seal: () => commands.seal(process.cwd(), { json: options.json === true }),
+        verify: () => commands.verify(process.cwd(), { json: options.json === true }),
         start: () => commands.start(),
         // Context (for Claude templates)
         context: (p) => commands.context(p),

package/core/schemas/analysis.ts

@@ -2,37 +2,80 @@
  * Analysis Schema
  *
  * Defines the structure for analysis.json - repository analysis.
+ * Supports a 3-state lifecycle: DRAFT → VERIFIED → SEALED (PRJ-263).
  */
 
-import type { ModelMetadata } from './model'
+import { z } from 'zod'
+import { ModelMetadataSchema } from './model'
 
-export interface CodePattern {
-  name: string
-  description: string
-  location?: string
-}
+// =============================================================================
+// Zod Schemas - Source of Truth
+// =============================================================================
 
-export interface AntiPattern {
-  issue: string
-  file: string
-  suggestion: string
-}
+export const AnalysisStatusSchema = z.enum(['draft', 'verified', 'sealed'])
+
+export const CodePatternSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  location: z.string().optional(),
+})
 
-export interface AnalysisSchema {
-  projectId: string
-  languages: string[]
-  frameworks: string[]
-  packageManager?: string
-  sourceDir?: string
-  testDir?: string
-  configFiles: string[]
-  fileCount: number
-  patterns: CodePattern[]
-  antiPatterns: AntiPattern[]
-  analyzedAt: string // ISO8601
+export const AntiPatternSchema = z.object({
+  issue: z.string(),
+  file: z.string(),
+  suggestion: z.string(),
+})
+
+export const AnalysisItemSchema = z.object({
+  projectId: z.string(),
+  languages: z.array(z.string()),
+  frameworks: z.array(z.string()),
+  packageManager: z.string().optional(),
+  sourceDir: z.string().optional(),
+  testDir: z.string().optional(),
+  configFiles: z.array(z.string()),
+  fileCount: z.number(),
+  patterns: z.array(CodePatternSchema),
+  antiPatterns: z.array(AntiPatternSchema),
+  analyzedAt: z.string(), // ISO8601
   /** Which AI model was used for this analysis (PRJ-265) */
-  modelMetadata?: ModelMetadata
-}
+  modelMetadata: ModelMetadataSchema.optional(),
+
+  // Sealable analysis fields (PRJ-263)
+  /** Lifecycle status: draft (regenerable), verified (confirmed correct), sealed (locked) */
+  status: AnalysisStatusSchema.default('draft'),
+  /** Git commit hash at the time of analysis */
+  commitHash: z.string().optional(),
+  /** SHA-256 signature of analysis content + commit hash */
+  signature: z.string().optional(),
+  /** When the analysis was sealed */
+  sealedAt: z.string().optional(), // ISO8601
+  /** When the analysis was verified */
+  verifiedAt: z.string().optional(), // ISO8601
+})
+
+// =============================================================================
+// Inferred Types - Backward Compatible
+// =============================================================================
+
+export type AnalysisStatus = z.infer<typeof AnalysisStatusSchema>
+export type CodePattern = z.infer<typeof CodePatternSchema>
+export type AntiPattern = z.infer<typeof AntiPatternSchema>
+/** Use z.input so optional fields with defaults (like status) remain optional in creation */
+export type AnalysisSchema = z.input<typeof AnalysisItemSchema>
+
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+
+/** Parse and validate analysis.json content */
+export const parseAnalysis = (data: unknown): z.infer<typeof AnalysisItemSchema> =>
+  AnalysisItemSchema.parse(data)
+export const safeParseAnalysis = (data: unknown) => AnalysisItemSchema.safeParse(data)
+
+// =============================================================================
+// Defaults
+// =============================================================================
 
 export const DEFAULT_ANALYSIS: Omit<AnalysisSchema, 'projectId'> = {
   languages: [],
@@ -42,4 +85,5 @@ export const DEFAULT_ANALYSIS: Omit<AnalysisSchema, 'projectId'> = {
   patterns: [],
   antiPatterns: [],
   analyzedAt: new Date().toISOString(),
+  status: 'draft',
 }

package/core/services/context-selector.ts

@@ -29,14 +29,20 @@ export interface SelectedContext {
   }
 }
 
-/** Default token budget for context selection (increased for 200K+ context models) */
+/**
+ * Default token budget for context selection.
+ * When a TokenBudgetCoordinator is available, this is overridden
+ * by the coordinator's file allocation.
+ *
+ * @see PRJ-266
+ */
 const DEFAULT_TOKEN_BUDGET = 80_000
 
 export interface ContextSelectionOptions {
   maxFiles?: number // Max files to return (default: 50)
   minScore?: number // Min relevance score (default: 30)
   includeGeneral?: boolean // Include 'general' domain files (default: true)
-  tokenBudget?: number // Max estimated tokens (default: 80000)
+  tokenBudget?: number // Max estimated tokens (default: 80000, or from coordinator)
 }
 
 // ============================================================================

package/core/services/sync-service.ts

@@ -31,6 +31,7 @@ import { getErrorMessage } from '../errors'
 import commandInstaller from '../infrastructure/command-installer'
 import configManager from '../infrastructure/config-manager'
 import pathManager from '../infrastructure/path-manager'
+import { analysisStorage } from '../storage/analysis-storage'
 import { metricsStorage } from '../storage/metrics-storage'
 import type {
   GitData,
@@ -176,6 +177,7 @@ class SyncService {
         this.updateProjectJson(git, stats),
         this.updateStateJson(stats, stack),
         this.logToMemory(git, stats),
+        this.saveDraftAnalysis(git, stats, stack),
       ])
 
       // 9. Record metrics for value dashboard
@@ -1102,6 +1104,39 @@ You are the ${name} expert for this project. Apply best practices for the detect
     }
   }
 
+  // ==========================================================================
+  // DRAFT ANALYSIS (PRJ-263)
+  // ==========================================================================
+
+  /**
+   * Save sync results as a draft analysis.
+   * Preserves existing sealed analysis — only the draft is overwritten.
+   */
+  private async saveDraftAnalysis(
+    git: GitData,
+    stats: ProjectStats,
+    _stack: StackDetection
+  ): Promise<void> {
+    try {
+      const commitHash = git.recentCommits[0]?.hash || null
+
+      await analysisStorage.saveDraft(this.projectId!, {
+        projectId: this.projectId!,
+        languages: stats.languages,
+        frameworks: stats.frameworks,
+        configFiles: [],
+        fileCount: stats.fileCount,
+        patterns: [],
+        antiPatterns: [],
+        analyzedAt: dateHelper.getTimestamp(),
+        status: 'draft',
+        commitHash: commitHash ?? undefined,
+      })
+    } catch (error) {
+      log.debug('Failed to save draft analysis (non-critical)', { error: getErrorMessage(error) })
+    }
+  }
+
   // ==========================================================================
   // HELPERS
   // ==========================================================================