prjct-cli 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## [1.11.0] - 2026-02-09
+
+### Features
+
+- implement sealable analysis with commit-hash signature (PRJ-263) (#153)
+
+
+## [1.11.0] - 2026-02-08
+
+### Features
+- **Sealable Analysis**: 3-state lifecycle (draft/verified/sealed) with SHA-256 commit-hash signatures (PRJ-263)
+- **Dual Storage**: Re-sync creates drafts without destroying sealed analysis — only sealed feeds task context
+- **Staleness Detection**: Warns when HEAD moves past the sealed commit hash
+- **Seal & Verify Commands**: `prjct seal` locks draft analysis, `prjct verify` checks integrity
+
+### Implementation Details
+New `analysis-storage.ts` extends StorageManager with dual storage (draft + sealed). Analysis schema rewritten as Zod schemas with runtime validation. Sync service writes drafts in parallel with existing writes. Canonical JSON representation ensures deterministic SHA-256 signatures.
+
+Key changes:
+- `core/schemas/analysis.ts` — Full rewrite: plain interfaces → Zod schemas with `AnalysisStatusSchema`, `AnalysisItemSchema`
+- `core/storage/analysis-storage.ts` — New: dual storage, sealing, verification, staleness detection
+- `core/services/sync-service.ts` — Added `saveDraftAnalysis()` to parallel writes
+- `core/commands/analysis.ts` — Added `seal()` and `verify()` command methods
+- `core/commands/register.ts`, `core/index.ts` — Registered new commands
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync` — verify draft analysis is created in storage
+2. Run `prjct seal` — verify analysis is locked with SHA-256 signature
+3. Run `prjct verify` — verify signature matches
+4. Run `prjct sync` again — verify sealed analysis is preserved, new draft created
+5. Make a commit, run `prjct status` — verify staleness detection warns about diverged commits
+
+#### For Users
+- **What changed:** Analysis results can now be locked (sealed) so re-syncing doesn't overwrite verified context
+- **How to use:** Run `prjct seal` after reviewing sync results, `prjct verify` to check integrity
+- **Breaking changes:** None — old analysis files parse with `status: 'draft'` default
+
+## [1.10.0] - 2026-02-08
+
+### Features
+
+- redesign prompt assembly with correct section ordering + anti-hallucination (PRJ-301) (#152)
+- add coordinated global token budget (PRJ-266) (#151)
+
+
+## [1.12.0] - 2026-02-07
+
+### Features
+- **Prompt Assembly Redesign**: Correct section ordering based on research of 25+ system prompts (PRJ-301)
+- **Environment Block**: Structured `<env>` block with project, git, platform, runtime, and model metadata
+- **Anti-Hallucination Block**: Explicit availability/unavailability grounding injected BEFORE task context
+- **Token Efficiency Directive**: Conciseness rules appended to every prompt
+
+### Implementation Details
+Redesigned `prompt-builder.ts` section ordering to follow research-backed pattern:
+Identity → Environment → Ground Truth → Capabilities → Constraints → Task Context → Task → Output Schema → Efficiency
+
+Key changes:
+- New `environment-block.ts`: Generates `<env>` XML block with auto-detected runtime, platform, and normalized names
+- New `anti-hallucination.ts`: Generates constraints block from sealed analysis (available tech, absent domains, grounding rules)
+- Moved template content (task instructions) to section 7 — LLM knows identity, env, and rules before reading task
+- Anti-hallucination block placed at section 5 (before task context), replacing old `RULES (CRITICAL)` at the end
+- Added `buildEfficiencyDirective()` with conciseness rules (max 4 lines, no preamble/postamble)
+- Exported `PROMPT_SECTION_ORDER` constant and `SectionPriority` type for budget trimming
+- Kept `buildCriticalRules()` as fallback when project context unavailable
+
+### Learnings
+- Zod `.default()` only applies during `.parse()` — raw object construction skips defaults, use `??` fallback
+- Renaming prompt section headers breaks existing test assertions — always update test matchers
+- Template position matters: placing task instructions after constraints improves LLM grounding
+
+### Test Plan
+
+#### For QA
+1. Run `bun test` — all 719 tests pass (0 failures)
+2. Run `bun run build` — build succeeds
+3. Verify `<env>` block appears in generated prompts before constraints
+4. Verify `CONSTRAINTS (Read Before Acting)` appears before template content
+5. Verify `OUTPUT RULES` section appears at end of prompt
+6. Check `AVAILABLE` and `NOT PRESENT` lists reflect project tech stack
+7. Run `prjct sync` — prompt assembly still works end-to-end
+
+#### For Users
+Prompts sent to AI models are now structured with research-backed section ordering, reducing hallucinations and improving response conciseness. No user action required — improvements are automatic.
+
+## [1.11.0] - 2026-02-07
+
+### Features
+- **Token Budget Coordinator**: Centralized token budget management across all context-loading components (PRJ-266)
+
+### Implementation Details
+Created `TokenBudgetCoordinator` class that manages the global token budget based on model context windows. Key features:
+- Model context window registry (Claude 200K, Gemini 1M) with automatic budget calculation
+- Input/output budget split: 65% input, 35% reserved for output
+- Priority-based allocation: state (P1) > injection context (P2) > file content (P3)
+- Request/record API for usage tracking with overflow detection
+- Integrated into `injection-validator.ts`, `prompt-builder.ts`, and `context-selector.ts`
+- Backward compatible: falls back to existing defaults when no coordinator is set
+
+### Test Plan
+
+#### For QA
+1. Create coordinator with `'sonnet'` → input budget = 130K, output reserve = 70K
+2. Create with `'2.5-pro'` (Gemini) → input budget = 650K (5x Claude)
+3. Request tokens up to allocation limit → verify grants are capped
+4. Exhaust a category budget → verify subsequent requests return 0
+5. Verify `budgetsFromCoordinator()` uses coordinator's injection allocation
+6. Run full test suite → all 705 tests pass
+
+#### For Users
+Token budgets are now centrally coordinated based on the model's context window. Larger models get proportionally larger budgets automatically. No breaking changes.
+
 ## [1.9.0] - 2026-02-07
 
 ### Features
@@ -11,7 +125,6 @@
 
 - replace keyword domain detection with LLM semantic classification (PRJ-299) (#148)
 
-
 ## [1.10.0] - 2026-02-07
 
 ### Features

package/core/__tests__/agentic/prompt-assembly.test.ts

@@ -0,0 +1,298 @@
+/**
+ * Prompt Assembly Tests (PRJ-301)
+ *
+ * Tests for the redesigned prompt assembly:
+ * - Section ordering (Identity → Env → Ground Truth → ... → Efficiency)
+ * - Environment block generation
+ * - Anti-hallucination block generation
+ * - Token efficiency directive
+ * - Budget trimming with priorities
+ */
+
+import { beforeEach, describe, expect, it } from 'bun:test'
+import {
+  buildAntiHallucinationBlock,
+  type ProjectGroundTruth,
+} from '../../agentic/anti-hallucination'
+import { buildEnvironmentBlock, type EnvironmentBlockInput } from '../../agentic/environment-block'
+import promptBuilder, { PROMPT_SECTION_ORDER } from '../../agentic/prompt-builder'
+
+// =============================================================================
+// Environment Block
+// =============================================================================
+
+describe('Environment Block (PRJ-301)', () => {
+  it('should generate <env> block with all fields', () => {
+    const input: EnvironmentBlockInput = {
+      projectName: 'my-app',
+      projectPath: '/home/user/my-app',
+      isGitRepo: true,
+      gitBranch: 'feature/login',
+      platform: 'darwin',
+      runtime: 'bun',
+      date: '2026-02-07',
+      model: 'opus',
+      provider: 'claude',
+    }
+
+    const block = buildEnvironmentBlock(input)
+
+    expect(block).toContain('<env>')
+    expect(block).toContain('</env>')
+    expect(block).toContain('project: my-app')
+    expect(block).toContain('path: /home/user/my-app')
+    expect(block).toContain('git: true')
+    expect(block).toContain('branch: feature/login')
+    expect(block).toContain('platform: macOS')
+    expect(block).toContain('runtime: bun')
+    expect(block).toContain('date: 2026-02-07')
+    expect(block).toContain('model: opus')
+    expect(block).toContain('provider: claude')
+  })
+
+  it('should omit undefined fields', () => {
+    const input: EnvironmentBlockInput = {
+      projectName: 'my-app',
+      projectPath: '/test',
+    }
+
+    const block = buildEnvironmentBlock(input)
+
+    expect(block).toContain('project: my-app')
+    expect(block).toContain('path: /test')
+    expect(block).not.toContain('model:')
+    expect(block).not.toContain('provider:')
+    expect(block).not.toContain('branch:')
+  })
+
+  it('should normalize platform names', () => {
+    expect(
+      buildEnvironmentBlock({ projectName: 'x', projectPath: '/x', platform: 'darwin' })
+    ).toContain('platform: macOS')
+    expect(
+      buildEnvironmentBlock({ projectName: 'x', projectPath: '/x', platform: 'linux' })
+    ).toContain('platform: Linux')
+    expect(
+      buildEnvironmentBlock({ projectName: 'x', projectPath: '/x', platform: 'win32' })
+    ).toContain('platform: Windows')
+  })
+
+  it('should auto-detect runtime and date when not provided', () => {
+    const block = buildEnvironmentBlock({ projectName: 'x', projectPath: '/x' })
+
+    // Should have a runtime (bun or node)
+    expect(block).toMatch(/runtime: (bun|node)/)
+    // Should have a date in YYYY-MM-DD format
+    expect(block).toMatch(/date: \d{4}-\d{2}-\d{2}/)
+  })
+})
+
+// =============================================================================
+// Anti-Hallucination Block
+// =============================================================================
+
+describe('Anti-Hallucination Block (PRJ-301)', () => {
+  it('should generate constraints block with availability', () => {
+    const truth: ProjectGroundTruth = {
+      projectPath: '/home/user/my-app',
+      language: 'TypeScript',
+      framework: 'Hono',
+      techStack: ['Hono', 'Zod', 'Vitest'],
+      domains: {
+        hasFrontend: false,
+        hasBackend: true,
+        hasDatabase: false,
+        hasTesting: true,
+        hasDocker: false,
+      },
+      fileCount: 292,
+      availableAgents: ['backend', 'testing'],
+    }
+
+    const block = buildAntiHallucinationBlock(truth)
+
+    // Section header
+    expect(block).toContain('CONSTRAINTS (Read Before Acting)')
+
+    // Availability
+    expect(block).toContain('AVAILABLE in this project: TypeScript, Hono, Zod, Vitest')
+
+    // Unavailability (no frontend, no database, no docker)
+    expect(block).toContain('NOT PRESENT:')
+    expect(block).toContain('Frontend (UI/components)')
+    expect(block).toContain('Database (SQL/ORM)')
+    expect(block).toContain('Docker/containers')
+
+    // Should NOT list present domains as absent
+    expect(block).not.toContain('NOT PRESENT: Backend')
+    expect(block).not.toContain('NOT PRESENT: Testing')
+
+    // Agents
+    expect(block).toContain('AGENTS: backend, testing')
+
+    // Grounding rules
+    expect(block).toContain('SCOPE: Only files in `/home/user/my-app` are accessible.')
+    expect(block).toContain('Do NOT infer or guess paths')
+    expect(block).toContain('NEVER assume a library is available')
+    expect(block).toContain('trust this section')
+
+    // File count
+    expect(block).toContain('292 files in project')
+  })
+
+  it('should handle minimal input', () => {
+    const truth: ProjectGroundTruth = {
+      projectPath: '/test',
+    }
+
+    const block = buildAntiHallucinationBlock(truth)
+
+    expect(block).toContain('CONSTRAINTS')
+    expect(block).toContain('SCOPE: Only files in `/test` are accessible.')
+    // Should not have AVAILABLE or NOT PRESENT lines
+    expect(block).not.toContain('AVAILABLE in this project:')
+    expect(block).not.toContain('NOT PRESENT:')
+  })
+
+  it('should not duplicate framework in techStack listing', () => {
+    const truth: ProjectGroundTruth = {
+      projectPath: '/test',
+      language: 'TypeScript',
+      framework: 'Next.js',
+      techStack: ['Next.js', 'React', 'Tailwind'],
+    }
+
+    const block = buildAntiHallucinationBlock(truth)
+
+    // Next.js should appear once (from framework), not duplicated from techStack
+    const matches = block.match(/Next\.js/g)
+    expect(matches?.length).toBe(1)
+  })
+})
+
+// =============================================================================
+// Section Ordering
+// =============================================================================
+
+describe('Prompt Section Ordering (PRJ-301)', () => {
+  let builder: typeof promptBuilder
+
+  beforeEach(() => {
+    builder = promptBuilder
+    builder.resetContext()
+  })
+
+  it('should define correct section order constant', () => {
+    expect(PROMPT_SECTION_ORDER).toEqual([
+      'identity',
+      'environment',
+      'ground_truth',
+      'capabilities',
+      'constraints',
+      'task_context',
+      'task',
+      'output_schema',
+      'efficiency',
+    ])
+  })
+
+  it('should place environment block before constraints', async () => {
+    const template = {
+      frontmatter: { description: 'Test', 'allowed-tools': ['Read'] },
+      content: '## Instructions\nDo the thing',
+    }
+    const context = { projectPath: '/test', files: ['a.js'] }
+
+    const prompt = await builder.build(template, context, {})
+
+    const envPos = prompt.indexOf('<env>')
+    const constraintsPos = prompt.indexOf('CONSTRAINTS')
+    expect(envPos).toBeGreaterThan(-1)
+    expect(constraintsPos).toBeGreaterThan(-1)
+    expect(envPos).toBeLessThan(constraintsPos)
+  })
+
+  it('should place constraints before task template content', async () => {
+    const template = {
+      frontmatter: { description: 'Test' },
+      content: '## UNIQUE_TEMPLATE_MARKER\nFollow these steps',
+    }
+    const context = { projectPath: '/test', files: ['a.js'] }
+
+    const prompt = await builder.build(template, context, {})
+
+    const constraintsPos = prompt.indexOf('CONSTRAINTS')
+    const templatePos = prompt.indexOf('UNIQUE_TEMPLATE_MARKER')
+    expect(constraintsPos).toBeGreaterThan(-1)
+    expect(templatePos).toBeGreaterThan(-1)
+    expect(constraintsPos).toBeLessThan(templatePos)
+  })
+
+  it('should place identity (TASK:) at the beginning', async () => {
+    const template = {
+      frontmatter: { description: 'My Task' },
+      content: '## Flow\nStep 1',
+    }
+    const context = { projectPath: '/test' }
+
+    const prompt = await builder.build(template, context, {})
+
+    const taskPos = prompt.indexOf('TASK: My Task')
+    expect(taskPos).toBeLessThan(50)
+  })
+
+  it('should place efficiency directive at the end', async () => {
+    const template = {
+      frontmatter: { description: 'Test' },
+      content: '## Flow\nStep 1',
+    }
+    const context = { projectPath: '/test' }
+
+    const prompt = await builder.build(template, context, {})
+
+    const efficiencyPos = prompt.indexOf('OUTPUT RULES')
+    const executePos = prompt.indexOf('EXECUTE:')
+    expect(efficiencyPos).toBeGreaterThan(-1)
+    expect(executePos).toBeGreaterThan(-1)
+    // Should be in the last ~300 chars of the prompt
+    expect(prompt.length - executePos).toBeLessThan(300)
+  })
+})
+
+// =============================================================================
+// Token Efficiency Directive
+// =============================================================================
+
+describe('Token Efficiency Directive (PRJ-301)', () => {
+  let builder: typeof promptBuilder
+
+  beforeEach(() => {
+    builder = promptBuilder
+    builder.resetContext()
+  })
+
+  it('should include efficiency rules in every prompt', async () => {
+    const template = {
+      frontmatter: { description: 'Test' },
+      content: '## Flow\nStep 1',
+    }
+    const context = { projectPath: '/test' }
+
+    const prompt = await builder.build(template, context, {})
+
+    expect(prompt).toContain('OUTPUT RULES')
+    expect(prompt).toContain('Be concise')
+    expect(prompt).toContain('No preamble')
+    expect(prompt).toContain('No postamble')
+    expect(prompt).toContain('EXECUTE:')
+  })
+
+  it('should build efficiency directive as standalone method', () => {
+    const directive = builder.buildEfficiencyDirective()
+
+    expect(directive).toContain('Maximum 4 lines')
+    expect(directive).toContain('No preamble')
+    expect(directive).toContain('Prefer structured output')
+    expect(directive).toContain('EXECUTE:')
+  })
+})

package/core/__tests__/agentic/prompt-builder.test.ts

@@ -107,7 +107,7 @@ describe('PromptBuilder', () => {
 
       const prompt = await builder.build(template, context, state)
 
-      expect(prompt).toContain('PATTERNS')
+      expect(prompt).toContain('STACK')
       expect(prompt).toContain('Node.js')
     })
 
@@ -187,7 +187,7 @@ describe('PromptBuilder', () => {
       expect(prompt).toContain('TASK:')
       expect(prompt).toContain('TOOLS:')
       expect(prompt).toContain('Flow')
-      expect(prompt).toContain('RULES (CRITICAL)')
+      expect(prompt).toContain('CONSTRAINTS (Read Before Acting)')
       expect(prompt).toContain('## FILES:')
     })