prjct-cli 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,139 @@
 # Changelog
 
+## [1.5.0] - 2026-02-06
+
+### Features
+
+- add citation format for context sources in templates (PRJ-113) (#117)
+
+
+## [1.4.2] - 2026-02-06
+
+### Features
+
+- **Source citations in context files (PRJ-113)**: All generated context files now include `<!-- source: file, type -->` HTML comments showing where each section's data was detected from
+
+### Implementation Details
+
+- Added `SourceInfo` type and `ContextSources` interface with `cite()` helper (`core/utils/citations.ts`)
+- Extended `ProjectContext` with optional `sources` field — backward compatible, falls back to `defaultSources()`
+- Added `buildSources()` to `sync-service.ts` — maps detected ecosystem/commands data to their source files (package.json, lock files, Cargo.toml, etc.)
+- Citations added to 4 markdown formatters: Claude, Cursor, Windsurf, Copilot. Continue.dev skipped (JSON has no comment syntax)
+- Context generator CLAUDE.md also updated with citation support
+- Source types: `detected` (from files), `user-defined` (from config), `inferred` (from heuristics)
+
+### Learnings
+
+- `context-generator.ts` and `formatters.ts` both independently generate CLAUDE.md content — both must be updated for consistent citations
+- Sources can be determined post-detection from data values rather than threading metadata through every detection method
+- Optional fields with fallback defaults (`sources?`) maintain backward compatibility without breaking existing callers
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync --yes` — verify generated context files contain `<!-- source: ... -->` comments
+2. Check CLAUDE.md citations before: THIS PROJECT, Commands, Code Conventions, PROJECT STATE
+3. Check `.cursor/rules/prjct.mdc` citations before Tech Stack and Commands
+4. Check `.windsurf/rules/prjct.md` citations before Stack and Commands
+5. Check `.github/copilot-instructions.md` citations before Project Info and Commands
+6. Verify `.continue/config.json` unchanged (JSON has no comments)
+7. Run `bun test` — all 416 tests pass
+
+#### For Users
+**What changed:** Context files now show where data came from via HTML comments
+**How to use:** Run `p. sync` — citations appear automatically
+**Breaking changes:** None
+
+## [1.4.1] - 2026-02-06
+
+### Improvements
+
+- **Better error messages for invalid commands (PRJ-98)**: Consistent, helpful CLI errors with did-you-mean suggestions and required parameter validation
+
+### Implementation Details
+
+- Added `UNKNOWN_COMMAND` and `MISSING_PARAM` error codes to centralized error catalog (`core/utils/error-messages.ts`)
+- Added `validateCommandParams()` — parses `CommandMeta.params` convention (`<required>` vs `[optional]`) and validates against actual CLI args before command execution
+- Added `findClosestCommand()` with Levenshtein edit distance (threshold ≤ 2) for did-you-mean suggestions on typos
+- All error paths now use `out.failWithHint()` for consistent formatting with hints, docs links, and file references
+- Deprecated and unimplemented command errors also upgraded to use `failWithHint()`
+
+### Learnings
+
+- `bin/prjct.ts` intercepts many commands (start, context, hooks, doctor, etc.) before `core/index.ts` — changes to dispatch only affect commands that reach core
+- Template-only commands (e.g. `task`) are defined in `command-data.ts` but not registered in the command registry — they don't get param validation via CLI
+- Levenshtein edit distance is simple to implement (~15 lines) and effective for CLI typo suggestions
+
+### Test Plan
+
+#### For QA
+1. `prjct xyzzy` → "Unknown command: xyzzy" with help hint
+2. `prjct snyc` → "Did you mean 'prjct sync'?"
+3. `prjct shp` → "Did you mean 'prjct ship'?"
+4. `prjct bug` (no args) → "Missing required parameter: description" with usage
+5. `prjct idea` (no args) → "Missing required parameter: description" with usage
+6. `prjct sync --yes` → works normally (no regression)
+7. `prjct dash compact` → works normally (no regression)
+
+#### For Users
+**What changed:** CLI now shows helpful error messages with suggestions when you mistype a command or forget a required argument.
+**How to use:** Just use prjct normally — errors are now more helpful automatically.
+**Breaking changes:** None
+
+## [1.4.0] - 2026-02-06
+
+### Features
+
+- programmatic verification checks for sync workflow (PRJ-106) (#115)
+
+## [1.3.1] - 2026-02-06
+
+### Features
+
+- **Programmatic verification checks for sync workflow (PRJ-106)**: Post-sync validation with built-in and custom checks
+
+### Implementation Details
+
+New `SyncVerifier` service (`core/services/sync-verifier.ts`) that runs verification checks after every sync. Three built-in checks run automatically:
+- **Context files exist** — verifies `context/CLAUDE.md` was generated
+- **JSON files valid** — validates `storage/state.json` syntax
+- **No sensitive data** — scans context files for leaked API keys, passwords, secrets
+
+Custom checks configurable in `.prjct/prjct.config.json`:
+```json
+{
+  "verification": {
+    "checks": [
+      { "name": "Lint CLAUDE.md", "command": "npx markdownlint CLAUDE.md" },
+      { "name": "Custom validator", "script": ".prjct/verify.sh" }
+    ],
+    "failFast": false
+  }
+}
+```
+
+Integration: wired into `sync-service.ts` after file generation (step 11), results returned in `SyncResult.verification`. Display in `showSyncResult()` shows pass/fail per check with timing.
+
+### Learnings
+
+- Non-critical verification must be wrapped in try/catch so it never breaks the sync workflow
+- Config types must match optional fields between `LocalConfig` and `VerificationConfig` (both `checks` must be optional)
+- Built-in + custom extensibility pattern (always run built-ins, then user commands) provides good defaults with flexibility
+
+### Test Plan
+
+#### For QA
+1. Run `prjct sync --yes` — verify "Verified" section with 3 checks passing
+2. Add custom check to `.prjct/prjct.config.json` — verify it runs after sync
+3. Add failing custom check (`command: "exit 1"`) — verify `✗` with error
+4. Set `failFast: true` with failing check — verify remaining checks skipped
+5. Run `bun run build && bun run typecheck` — zero errors
+
+#### For Users
+**What changed:** `prjct sync` now validates generated output with pass/fail checks
+**How to use:** Built-in checks run automatically. Add custom checks in `.prjct/prjct.config.json`
+**Breaking changes:** None
+
 ## [1.3.0] - 2026-02-06
 
 ### Features

package/core/__tests__/ai-tools/formatters.test.ts

@@ -2,6 +2,7 @@
  * Tests for AI Tools Formatters
  *
  * @see PRJ-122
+ * @see PRJ-113 (citation support)
  */
 
 import { describe, expect, test } from 'bun:test'
@@ -15,6 +16,7 @@ import {
   type ProjectContext,
 } from '../../ai-tools/formatters'
 import { AI_TOOLS, getAIToolConfig } from '../../ai-tools/registry'
+import { type ContextSources, cite, defaultSources } from '../../utils/citations'
 
 // =============================================================================
 // Test Fixtures
@@ -356,3 +358,119 @@ describe('Formatter Edge Cases', () => {
     expect(claudeResult).toContain('@scope/my-project')
   })
 })
+
+// =============================================================================
+// Citation Tests (PRJ-113)
+// =============================================================================
+
+const mockSources: ContextSources = {
+  name: { file: 'package.json', type: 'detected' },
+  version: { file: 'package.json', type: 'detected' },
+  ecosystem: { file: 'package.json', type: 'detected' },
+  languages: { file: 'package.json', type: 'detected' },
+  frameworks: { file: 'package.json', type: 'detected' },
+  commands: { file: 'bun.lockb', type: 'detected' },
+  projectType: { file: 'file count + frameworks', type: 'inferred' },
+  git: { file: 'git', type: 'detected' },
+}
+
+const ctxWithSources: ProjectContext = {
+  ...mockContext,
+  sources: mockSources,
+}
+
+describe('cite() helper', () => {
+  test('generates HTML comment with file and type', () => {
+    const result = cite({ file: 'package.json', type: 'detected' })
+    expect(result).toBe('<!-- source: package.json, detected -->')
+  })
+
+  test('supports inferred type', () => {
+    const result = cite({ file: 'file count + frameworks', type: 'inferred' })
+    expect(result).toBe('<!-- source: file count + frameworks, inferred -->')
+  })
+
+  test('supports user-defined type', () => {
+    const result = cite({ file: 'prjct.yaml', type: 'user-defined' })
+    expect(result).toBe('<!-- source: prjct.yaml, user-defined -->')
+  })
+})
+
+describe('defaultSources()', () => {
+  test('returns all source fields', () => {
+    const sources = defaultSources()
+    expect(sources.name).toBeDefined()
+    expect(sources.version).toBeDefined()
+    expect(sources.ecosystem).toBeDefined()
+    expect(sources.languages).toBeDefined()
+    expect(sources.frameworks).toBeDefined()
+    expect(sources.commands).toBeDefined()
+    expect(sources.projectType).toBeDefined()
+    expect(sources.git).toBeDefined()
+  })
+
+  test('git source is always "git"', () => {
+    const sources = defaultSources()
+    expect(sources.git.file).toBe('git')
+    expect(sources.git.type).toBe('detected')
+  })
+})
+
+describe('Citation integration', () => {
+  test('Claude format includes source citations', () => {
+    const result = formatForClaude(ctxWithSources, AI_TOOLS.claude)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('Cursor format includes source citations', () => {
+    const result = formatForCursor(ctxWithSources, AI_TOOLS.cursor)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('Windsurf format includes source citations', () => {
+    const result = formatForWindsurf(ctxWithSources, AI_TOOLS.windsurf)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('Copilot format includes source citations', () => {
+    const result = formatForCopilot(ctxWithSources, AI_TOOLS.copilot)
+
+    expect(result).toContain('<!-- source: package.json, detected -->')
+    expect(result).toContain('<!-- source: bun.lockb, detected -->')
+  })
+
+  test('formatters work without sources (backward compatible)', () => {
+    const ctxNoSources = { ...mockContext }
+    delete ctxNoSources.sources
+
+    // Should not throw
+    expect(() => formatForClaude(ctxNoSources, AI_TOOLS.claude)).not.toThrow()
+    expect(() => formatForCursor(ctxNoSources, AI_TOOLS.cursor)).not.toThrow()
+    expect(() => formatForWindsurf(ctxNoSources, AI_TOOLS.windsurf)).not.toThrow()
+    expect(() => formatForCopilot(ctxNoSources, AI_TOOLS.copilot)).not.toThrow()
+
+    // Should still contain default citation comments
+    const result = formatForClaude(ctxNoSources, AI_TOOLS.claude)
+    expect(result).toContain('<!-- source:')
+  })
+
+  test('Claude format has citations before each major section', () => {
+    const result = formatForClaude(ctxWithSources, AI_TOOLS.claude)
+
+    // Ecosystem citation before project type
+    const ecosystemIdx = result.indexOf('<!-- source: package.json, detected -->')
+    const projectTypeIdx = result.indexOf('**Type:**')
+    expect(ecosystemIdx).toBeLessThan(projectTypeIdx)
+
+    // Commands citation before commands table
+    const commandsCiteIdx = result.indexOf('<!-- source: bun.lockb, detected -->')
+    const commandsTableIdx = result.indexOf('| Action | Command |')
+    expect(commandsCiteIdx).toBeLessThan(commandsTableIdx)
+  })
+})

package/core/ai-tools/formatters.ts

@@ -8,6 +8,7 @@
  * - Windsurf: Similar to Cursor
  */
 
+import { type ContextSources, cite, defaultSources } from '../utils/citations'
 import type { AIToolConfig } from './registry'
 
 export interface ProjectContext {
@@ -35,6 +36,7 @@ export interface ProjectContext {
     workflow: string[]
     domain: string[]
   }
+  sources?: ContextSources
 }
 
 /**
@@ -42,6 +44,8 @@ export interface ProjectContext {
  * Detailed markdown with full context
  */
 export function formatForClaude(ctx: ProjectContext, _config: AIToolConfig): string {
+  const s = ctx.sources || defaultSources()
+
   return `# ${ctx.name} - Project Rules
 <!-- projectId: ${ctx.projectId} -->
 <!-- Generated: ${new Date().toISOString()} -->
@@ -49,11 +53,13 @@ export function formatForClaude(ctx: ProjectContext, _config: AIToolConfig): str
 
 ## THIS PROJECT (${ctx.ecosystem})
 
+${cite(s.ecosystem)}
 **Type:** ${ctx.projectType}
 **Path:** ${ctx.repoPath}
 
 ### Commands (USE THESE, NOT OTHERS)
 
+${cite(s.commands)}
 | Action | Command |
 |--------|---------|
 | Install dependencies | \`${ctx.commands.install}\` |
@@ -65,7 +71,9 @@ export function formatForClaude(ctx: ProjectContext, _config: AIToolConfig): str
 
 ### Code Conventions
 
+${cite(s.languages)}
 - **Languages**: ${ctx.languages.join(', ') || 'Not detected'}
+${cite(s.frameworks)}
 - **Frameworks**: ${ctx.frameworks.join(', ') || 'Not detected'}
 
 ---
@@ -93,6 +101,7 @@ p. sync → p. task "desc" → [work] → p. done → p. ship
 
 ## PROJECT STATE
 
+${cite(s.name)}
 | Field | Value |
 |-------|-------|
 | Name | ${ctx.name} |
@@ -120,6 +129,7 @@ Load from \`~/.prjct-cli/projects/${ctx.projectId}/agents/\`:
  * @see https://cursor.com/docs/context/rules
  */
 export function formatForCursor(ctx: ProjectContext, _config: AIToolConfig): string {
+  const s = ctx.sources || defaultSources()
   const lines: string[] = []
 
   // MDC format with YAML frontmatter
@@ -135,6 +145,7 @@ export function formatForCursor(ctx: ProjectContext, _config: AIToolConfig): str
   lines.push('')
 
   // Tech stack
+  lines.push(cite(s.languages))
   lines.push('## Tech Stack')
   if (ctx.languages.length > 0) {
     lines.push(`- Languages: ${ctx.languages.join(', ')}`)
@@ -145,6 +156,7 @@ export function formatForCursor(ctx: ProjectContext, _config: AIToolConfig): str
   lines.push('')
 
   // Commands
+  lines.push(cite(s.commands))
   lines.push('## Commands')
   lines.push(`- Install: \`${ctx.commands.install}\``)
   lines.push(`- Dev: \`${ctx.commands.dev}\``)
@@ -175,6 +187,7 @@ export function formatForCursor(ctx: ProjectContext, _config: AIToolConfig): str
  * Minimal bullet points
  */
 export function formatForCopilot(ctx: ProjectContext, _config: AIToolConfig): string {
+  const s = ctx.sources || defaultSources()
   const lines: string[] = []
 
   lines.push('# Copilot Instructions')
@@ -183,6 +196,7 @@ export function formatForCopilot(ctx: ProjectContext, _config: AIToolConfig): st
   lines.push('')
 
   // Key info
+  lines.push(cite(s.ecosystem))
   lines.push('## Project Info')
   lines.push(`- Type: ${ctx.projectType}`)
   lines.push(`- Stack: ${ctx.frameworks.join(', ') || ctx.ecosystem}`)
@@ -196,6 +210,7 @@ export function formatForCopilot(ctx: ProjectContext, _config: AIToolConfig): st
   lines.push('')
 
   // Commands
+  lines.push(cite(s.commands))
   lines.push('## Commands')
   lines.push(`- Test: \`${ctx.commands.test}\``)
   lines.push(`- Build: \`${ctx.commands.build}\``)
@@ -210,6 +225,7 @@ export function formatForCopilot(ctx: ProjectContext, _config: AIToolConfig): st
  * @see https://docs.windsurf.com/windsurf/cascade/memories
  */
 export function formatForWindsurf(ctx: ProjectContext, _config: AIToolConfig): string {
+  const s = ctx.sources || defaultSources()
   const lines: string[] = []
 
   // YAML frontmatter (Windsurf uses trigger: always_on instead of alwaysApply)
@@ -226,6 +242,7 @@ export function formatForWindsurf(ctx: ProjectContext, _config: AIToolConfig): s
   lines.push('')
 
   // Tech stack (concise)
+  lines.push(cite(s.languages))
   lines.push('## Stack')
   lines.push(`- ${ctx.languages.join(', ')}`)
   if (ctx.frameworks.length > 0) {
@@ -234,6 +251,7 @@ export function formatForWindsurf(ctx: ProjectContext, _config: AIToolConfig): s
   lines.push('')
 
   // Commands (essential only)
+  lines.push(cite(s.commands))
   lines.push('## Commands')
   lines.push('```bash')
   lines.push(`# Install`)

package/core/commands/analysis.ts

@@ -529,6 +529,28 @@ export class AnalysisCommands extends PrjctCommandsBase {
       console.log('')
     }
 
+    // ═══════════════════════════════════════════════════════════════════════
+    // VERIFICATION - Post-sync validation checks
+    // ═══════════════════════════════════════════════════════════════════════
+    if (result.verification) {
+      const v = result.verification
+      if (v.passed) {
+        const items = v.checks.map((c) => `${c.name} (${c.durationMs}ms)`)
+        out.section('Verified')
+        out.list(items, { bullet: '✓' })
+      } else {
+        out.section('Verification')
+        const items = v.checks.map((c) =>
+          c.passed ? `✓ ${c.name}` : `✗ ${c.name}${c.error ? ` — ${c.error}` : ''}`
+        )
+        out.list(items)
+        if (v.skippedCount > 0) {
+          out.warn(`${v.skippedCount} check(s) skipped (fail-fast)`)
+        }
+      }
+      console.log('')
+    }
+
     // ═══════════════════════════════════════════════════════════════════════
     // NEXT STEPS - Clear call to action
     // ═══════════════════════════════════════════════════════════════════════

package/core/index.ts

@@ -15,6 +15,7 @@ import type { CommandMeta } from './commands/registry'
 import { detectAllProviders, detectAntigravity } from './infrastructure/ai-provider'
 import configManager from './infrastructure/config-manager'
 import { sessionTracker } from './services/session-tracker'
+import { getError } from './utils/error-messages'
 import out from './utils/output'
 
 interface ParsedCommandArgs {
@@ -53,27 +54,34 @@ async function main(): Promise<void> {
     const cmd = commandRegistry.getByName(commandName)
 
     if (!cmd) {
-      console.error(`Unknown command: ${commandName}`)
-      console.error(`\nUse 'prjct --help' to see available commands.`)
+      const suggestion = findClosestCommand(commandName)
+      const hint = suggestion
+        ? `Did you mean 'prjct ${suggestion}'? Run 'prjct --help' for all commands`
+        : "Run 'prjct --help' to see available commands"
+      out.failWithHint(
+        getError('UNKNOWN_COMMAND', { message: `Unknown command: ${commandName}`, hint })
+      )
       out.end()
       process.exit(1)
     }
 
     // 2. Check if deprecated
     if (cmd.deprecated) {
-      console.error(`Command '${commandName}' is deprecated.`)
-      if (cmd.replacedBy) {
-        console.error(`Use 'prjct ${cmd.replacedBy}' instead.`)
-      }
+      const hint = cmd.replacedBy
+        ? `Use 'prjct ${cmd.replacedBy}' instead`
+        : "Run 'prjct --help' to see available commands"
+      out.failWithHint({ message: `Command '${commandName}' is deprecated`, hint })
       out.end()
       process.exit(1)
     }
 
     // 3. Check if implemented
     if (!cmd.implemented) {
-      console.error(`Command '${commandName}' exists but is not yet implemented.`)
-      console.error(`Check the roadmap or contribute: https://github.com/jlopezlira/prjct-cli`)
-      console.error(`\nUse 'prjct --help' to see available commands.`)
+      out.failWithHint({
+        message: `Command '${commandName}' is not yet implemented`,
+        hint: "Run 'prjct --help' to see available commands",
+        docs: 'https://github.com/jlopezlira/prjct-cli',
+      })
       out.end()
       process.exit(1)
     }
@@ -81,7 +89,15 @@ async function main(): Promise<void> {
     // 4. Parse arguments
     const { parsedArgs, options } = parseCommandArgs(cmd, rawArgs)
 
-    // 4.5. Session tracking — touch/create session before command execution
+    // 4.5. Validate required params
+    const paramError = validateCommandParams(cmd, parsedArgs)
+    if (paramError) {
+      out.failWithHint(paramError)
+      out.end()
+      process.exit(1)
+    }
+
+    // 4.6. Session tracking — touch/create session before command execution
     let projectId: string | null = null
     const commandStartTime = Date.now()
     try {
@@ -193,6 +209,71 @@ async function main(): Promise<void> {
   }
 }
 
+/**
+ * Validate that required params are provided
+ * Parses CommandMeta.params: <required> vs [optional]
+ */
+function validateCommandParams(
+  cmd: CommandMeta,
+  parsedArgs: string[]
+): import('./utils/error-messages').ErrorWithHint | null {
+  if (!cmd.params) return null
+
+  // Extract required params: tokens wrapped in <angle brackets>
+  const requiredParams = cmd.params.match(/<[^>]+>/g)
+  if (!requiredParams || requiredParams.length === 0) return null
+
+  // Check if enough positional args provided
+  if (parsedArgs.length < requiredParams.length) {
+    const paramNames = requiredParams.map((p) => p.slice(1, -1)).join(', ')
+    const usage = cmd.usage.terminal || `prjct ${cmd.name} ${cmd.params}`
+    return getError('MISSING_PARAM', {
+      message: `Missing required parameter: ${paramNames}`,
+      hint: `Usage: ${usage}`,
+    })
+  }
+
+  return null
+}
+
+/**
+ * Find closest matching command name for did-you-mean suggestions
+ * Uses Levenshtein edit distance — suggests if distance <= 2
+ */
+function findClosestCommand(input: string): string | null {
+  const allNames = commandRegistry.getAll().map((c) => c.name)
+  let best: string | null = null
+  let bestDist = Infinity
+
+  for (const name of allNames) {
+    const dist = editDistance(input.toLowerCase(), name.toLowerCase())
+    if (dist < bestDist) {
+      bestDist = dist
+      best = name
+    }
+  }
+
+  // Only suggest if edit distance is at most 2
+  return bestDist <= 2 ? best : null
+}
+
+function editDistance(a: string, b: string): number {
+  const m = a.length
+  const n = b.length
+  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0))
+  for (let i = 0; i <= m; i++) dp[i][0] = i
+  for (let j = 0; j <= n; j++) dp[0][j] = j
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] =
+        a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1])
+    }
+  }
+  return dp[m][n]
+}
+
 /**
  * Parse command arguments dynamically
  */

package/core/services/context-generator.ts

@@ -12,6 +12,7 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import pathManager from '../infrastructure/path-manager'
+import { type ContextSources, cite, defaultSources } from '../utils/citations'
 import dateHelper from '../utils/date-helper'
 import { mergePreservedSections, validatePreserveBlocks } from '../utils/preserve-sections'
 import { NestedContextResolver } from './nested-context-resolver'
@@ -103,13 +104,14 @@ export class ContextFileGenerator {
     git: GitData,
     stats: ProjectStats,
     commands: Commands,
-    agents: AgentInfo[]
+    agents: AgentInfo[],
+    sources?: ContextSources
   ): Promise<string[]> {
     const contextPath = path.join(this.config.globalPath, 'context')
 
     // Generate all context files IN PARALLEL
     await Promise.all([
-      this.generateClaudeMd(contextPath, git, stats, commands, agents),
+      this.generateClaudeMd(contextPath, git, stats, commands, agents, sources),
       this.generateNowMd(contextPath),
       this.generateNextMd(contextPath),
       this.generateIdeasMd(contextPath),
@@ -137,10 +139,12 @@ export class ContextFileGenerator {
     git: GitData,
     stats: ProjectStats,
     commands: Commands,
-    agents: AgentInfo[]
+    agents: AgentInfo[],
+    sources?: ContextSources
   ): Promise<void> {
     const workflowAgents = agents.filter((a) => a.type === 'workflow').map((a) => a.name)
     const domainAgents = agents.filter((a) => a.type === 'domain').map((a) => a.name)
+    const s = sources || defaultSources()
 
     const content = `# ${stats.name} - Project Rules
 <!-- projectId: ${this.config.projectId} -->
@@ -149,11 +153,13 @@ export class ContextFileGenerator {
 
 ## THIS PROJECT (${stats.ecosystem})
 
+${cite(s.ecosystem)}
 **Type:** ${stats.projectType}
 **Path:** ${this.config.projectPath}
 
 ### Commands (USE THESE, NOT OTHERS)
 
+${cite(s.commands)}
 | Action | Command |
 |--------|---------|
 | Install dependencies | \`${commands.install}\` |
@@ -165,7 +171,9 @@ export class ContextFileGenerator {
 
 ### Code Conventions
 
+${cite(s.languages)}
 - **Languages**: ${stats.languages.join(', ') || 'Not detected'}
+${cite(s.frameworks)}
 - **Frameworks**: ${stats.frameworks.join(', ') || 'Not detected'}
 
 ---
@@ -193,6 +201,7 @@ p. sync → p. task "desc" → [work] → p. done → p. ship
 
 ## PROJECT STATE
 
+${cite(s.name)}
 | Field | Value |
 |-------|-------|
 | Name | ${stats.name} |