prjct-cli 0.45.4 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## [0.46.0] - 2026-01-30
+
+### Features
+
+- preserve user customizations during sync - PRJ-115 (#70)
+
+
+## [0.46.0] - 2026-01-30
+
+### Added
+
+- **Preserve user customizations during sync** (PRJ-115)
+  - Wrap custom content in `<!-- prjct:preserve -->` markers
+  - Content survives `p. sync` regeneration
+  - Supports named sections: `<!-- prjct:preserve:my-rules -->`
+  - Works with CLAUDE.md, .cursorrules, and all context files
+
+
+## [0.45.5] - 2026-01-30
+
+### Bug Fixes
+
+- implement silent memory application - PRJ-103 (#69)
+
+
+## [0.45.5] - 2026-01-29
+
+### Changed
+
+- Remove meta-commentary from memory output (PRJ-103)
+  - "LEARNED PATTERNS" → "PROJECT DEFAULTS"
+  - "RELEVANT MEMORIES" → "CONTEXT"
+  - "Learned Patterns" → "Project Conventions"
+
+### Added
+
+- `lint:meta` script to catch meta-commentary anti-patterns
+
+
 ## [0.45.4] - 2026-01-29
 
 ### Bug Fixes

package/core/__tests__/utils/preserve-sections.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it } from 'bun:test'
+import {
+  extractPreservedContent,
+  extractPreservedSections,
+  hasPreservedSections,
+  mergePreservedSections,
+  stripPreservedSections,
+  validatePreserveBlocks,
+  wrapInPreserveMarkers,
+} from '../../utils/preserve-sections'
+
+describe('preserve-sections', () => {
+  describe('extractPreservedSections', () => {
+    it('should extract a single preserved section', () => {
+      const content = `# Header
+
+<!-- prjct:preserve -->
+My custom content
+<!-- /prjct:preserve -->
+
+# Footer`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(1)
+      expect(sections[0].content).toContain('My custom content')
+    })
+
+    it('should extract multiple preserved sections', () => {
+      const content = `# Header
+
+<!-- prjct:preserve -->
+First section
+<!-- /prjct:preserve -->
+
+Some content
+
+<!-- prjct:preserve -->
+Second section
+<!-- /prjct:preserve -->`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(2)
+      expect(sections[0].content).toContain('First section')
+      expect(sections[1].content).toContain('Second section')
+    })
+
+    it('should handle named sections', () => {
+      const content = `<!-- prjct:preserve:custom-rules -->
+My rules
+<!-- /prjct:preserve -->`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(1)
+      expect(sections[0].id).toBe('custom-rules')
+    })
+
+    it('should return empty array when no preserved sections', () => {
+      const content = '# Just normal content'
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(0)
+    })
+
+    it('should ignore unclosed preserve blocks', () => {
+      const content = `<!-- prjct:preserve -->
+No closing tag here`
+
+      const sections = extractPreservedSections(content)
+      expect(sections).toHaveLength(0)
+    })
+  })
+
+  describe('extractPreservedContent', () => {
+    it('should extract inner content without markers', () => {
+      const content = `<!-- prjct:preserve -->
+My content
+<!-- /prjct:preserve -->`
+
+      const inner = extractPreservedContent(content)
+      expect(inner).toHaveLength(1)
+      expect(inner[0]).toBe('My content')
+    })
+  })
+
+  describe('hasPreservedSections', () => {
+    it('should return true when preserved sections exist', () => {
+      const content = '<!-- prjct:preserve -->content<!-- /prjct:preserve -->'
+      expect(hasPreservedSections(content)).toBe(true)
+    })
+
+    it('should return false when no preserved sections', () => {
+      const content = '# Normal markdown'
+      expect(hasPreservedSections(content)).toBe(false)
+    })
+  })
+
+  describe('mergePreservedSections', () => {
+    it('should append preserved sections to new content', () => {
+      const oldContent = `# Old Header
+
+<!-- prjct:preserve -->
+# My Rules
+- Use tabs
+<!-- /prjct:preserve -->`
+
+      const newContent = `# New Generated Content
+
+This is fresh.`
+
+      const merged = mergePreservedSections(newContent, oldContent)
+
+      expect(merged).toContain('# New Generated Content')
+      expect(merged).toContain('My Rules')
+      expect(merged).toContain('Use tabs')
+      expect(merged).toContain('prjct:preserve')
+    })
+
+    it('should return new content unchanged when no preserved sections', () => {
+      const oldContent = '# Old content without preserve markers'
+      const newContent = '# New content'
+
+      const merged = mergePreservedSections(newContent, oldContent)
+      expect(merged).toBe(newContent)
+    })
+
+    it('should preserve multiple sections', () => {
+      const oldContent = `<!-- prjct:preserve -->
+Section 1
+<!-- /prjct:preserve -->
+
+<!-- prjct:preserve -->
+Section 2
+<!-- /prjct:preserve -->`
+
+      const newContent = '# New'
+
+      const merged = mergePreservedSections(newContent, oldContent)
+      expect(merged).toContain('Section 1')
+      expect(merged).toContain('Section 2')
+    })
+  })
+
+  describe('wrapInPreserveMarkers', () => {
+    it('should wrap content with default markers', () => {
+      const content = 'My content'
+      const wrapped = wrapInPreserveMarkers(content)
+
+      expect(wrapped).toContain('<!-- prjct:preserve -->')
+      expect(wrapped).toContain('My content')
+      expect(wrapped).toContain('<!-- /prjct:preserve -->')
+    })
+
+    it('should wrap content with named markers', () => {
+      const content = 'My content'
+      const wrapped = wrapInPreserveMarkers(content, 'custom')
+
+      expect(wrapped).toContain('<!-- prjct:preserve:custom -->')
+    })
+  })
+
+  describe('stripPreservedSections', () => {
+    it('should remove preserved sections from content', () => {
+      const content = `# Header
+
+<!-- prjct:preserve -->
+Custom stuff
+<!-- /prjct:preserve -->
+
+# Footer`
+
+      const stripped = stripPreservedSections(content)
+      expect(stripped).toContain('# Header')
+      expect(stripped).toContain('# Footer')
+      expect(stripped).not.toContain('Custom stuff')
+      expect(stripped).not.toContain('prjct:preserve')
+    })
+
+    it('should return content unchanged when no preserved sections', () => {
+      const content = '# Normal content'
+      const stripped = stripPreservedSections(content)
+      expect(stripped).toBe(content)
+    })
+  })
+
+  describe('validatePreserveBlocks', () => {
+    it('should validate correct blocks', () => {
+      const content = `<!-- prjct:preserve -->
+Content
+<!-- /prjct:preserve -->`
+
+      const result = validatePreserveBlocks(content)
+      expect(result.valid).toBe(true)
+      expect(result.errors).toHaveLength(0)
+    })
+
+    it('should detect mismatched markers', () => {
+      const content = `<!-- prjct:preserve -->
+Content without closing`
+
+      const result = validatePreserveBlocks(content)
+      expect(result.valid).toBe(false)
+      expect(result.errors.length).toBeGreaterThan(0)
+    })
+
+    it('should detect nested blocks', () => {
+      const content = `<!-- prjct:preserve -->
+<!-- prjct:preserve -->
+Nested
+<!-- /prjct:preserve -->
+<!-- /prjct:preserve -->`
+
+      const result = validatePreserveBlocks(content)
+      expect(result.valid).toBe(false)
+      expect(result.errors.some((e) => e.includes('Nested'))).toBe(true)
+    })
+  })
+})

package/core/agentic/prompt-builder.ts

@@ -174,7 +174,7 @@ class PromptBuilder {
     try {
       const patterns = await outcomeAnalyzer.detectPatterns(projectId)
       if (patterns.length > 0) {
-        parts.push('**Learned Patterns**')
+        parts.push('**Project Conventions**')
         for (const pattern of patterns.slice(0, 3)) {
           parts.push(`- ${pattern.description}`)
           if (pattern.suggestedAction) {
@@ -489,7 +489,7 @@ class PromptBuilder {
 
     // P1.1: Learned Patterns
     if (learnedPatterns && Object.keys(learnedPatterns).some((k) => learnedPatterns[k])) {
-      parts.push('\n## LEARNED PATTERNS (use these, do NOT ask user)\n')
+      parts.push('\n## PROJECT DEFAULTS (apply automatically)\n')
       for (const [key, value] of Object.entries(learnedPatterns)) {
         if (value) {
           parts.push(`- ${key}: ${value}\n`)
@@ -511,7 +511,7 @@ class PromptBuilder {
 
     // P3.3: Relevant Memories
     if (relevantMemories && relevantMemories.length > 0) {
-      parts.push('\n## RELEVANT MEMORIES (apply these learnings)\n')
+      parts.push('\n## CONTEXT (apply these)\n')
       for (const memory of relevantMemories) {
         parts.push(`- **${memory.title}**: ${memory.content}\n`)
         if (memory.tags && memory.tags.length > 0) {

package/core/ai-tools/generator.ts

@@ -7,6 +7,7 @@
 
 import fs from 'node:fs/promises'
 import path from 'node:path'
+import { mergePreservedSections } from '../utils/preserve-sections'
 import { getFormatter, type ProjectContext } from './formatters'
 import { AI_TOOLS, type AIToolConfig, DEFAULT_AI_TOOLS, getAIToolConfig } from './registry'
 
@@ -71,7 +72,7 @@ async function generateForTool(
 
   try {
     // Generate content
-    const content = formatter(context, config)
+    let content = formatter(context, config)
 
     // Determine output path
     let outputPath: string
@@ -84,6 +85,14 @@ async function generateForTool(
     // Ensure directory exists
     await fs.mkdir(path.dirname(outputPath), { recursive: true })
 
+    // Read existing file to preserve user customizations
+    try {
+      const existingContent = await fs.readFile(outputPath, 'utf-8')
+      content = mergePreservedSections(content, existingContent)
+    } catch {
+      // File doesn't exist yet - use generated content as-is
+    }
+
     // Write file
     await fs.writeFile(outputPath, content, 'utf-8')
 

package/core/cli/lint-meta-commentary.ts

@@ -0,0 +1,177 @@
+#!/usr/bin/env bun
+/**
+ * Lint rule: no-meta-commentary
+ *
+ * Catches AI memory meta-commentary patterns that should be avoided.
+ * Preferences should be presented as facts, not as memories.
+ *
+ * Anti-patterns:
+ * - "I remember you prefer..."
+ * - "Based on your history..."
+ * - "I've learned that..."
+ * - "From previous sessions..."
+ *
+ * Correct pattern:
+ * - "Use TypeScript strict mode" (not "I remember you like strict mode")
+ *
+ * @see PRJ-103
+ */
+
+import { readdir, readFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+
+const META_COMMENTARY_PATTERNS = [
+  // Direct memory references
+  /\bI remember\b/gi,
+  /\bI recall\b/gi,
+  /\bI('ve| have) learned\b/gi,
+
+  // History references
+  /\bBased on (your |)history\b/gi,
+  /\bFrom previous (session|conversation)s?\b/gi,
+  /\bIn (the |)past,? you\b/gi,
+
+  // Preference meta-commentary
+  /\byou (usually|typically|always|often) prefer\b/gi,
+  /\byou mentioned (before|earlier|previously)\b/gi,
+  /\blast time you\b/gi,
+
+  // Section headers that expose memory mechanism
+  /\bLEARNED PATTERNS\b/g,
+  /\bRELEVANT MEMORIES\b/g,
+  /\bLearned Patterns\b/g,
+  /\bRelevant Memories\b/g,
+]
+
+// Files/directories to skip
+const SKIP_PATTERNS = [
+  /node_modules/,
+  /\.git/,
+  /dist/,
+  /build/,
+  /coverage/,
+  /\.test\.ts$/,
+  /\.spec\.ts$/,
+  /lint-meta-commentary\.ts$/, // Skip self
+  /\/docs\//, // Skip documentation (describes features, not agent output)
+]
+
+// Only check these extensions
+const INCLUDE_EXTENSIONS = ['.ts', '.tsx', '.js', '.jsx', '.md']
+
+interface Violation {
+  file: string
+  line: number
+  column: number
+  match: string
+  pattern: string
+}
+
+async function* walkDir(dir: string): AsyncGenerator<string> {
+  const entries = await readdir(dir, { withFileTypes: true })
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name)
+
+    if (SKIP_PATTERNS.some((p) => p.test(fullPath))) {
+      continue
+    }
+
+    if (entry.isDirectory()) {
+      yield* walkDir(fullPath)
+    } else if (entry.isFile() && INCLUDE_EXTENSIONS.some((ext) => entry.name.endsWith(ext))) {
+      yield fullPath
+    }
+  }
+}
+
+async function checkFile(filePath: string): Promise<Violation[]> {
+  const violations: Violation[] = []
+  const content = await readFile(filePath, 'utf-8')
+  const lines = content.split('\n')
+
+  for (let lineNum = 0; lineNum < lines.length; lineNum++) {
+    const line = lines[lineNum]
+
+    // Skip comments - we only care about string literals that become agent output
+    const trimmed = line.trim()
+    if (
+      trimmed.startsWith('//') || // Inline comments
+      trimmed.startsWith('*') || // JSDoc/block comments
+      trimmed.startsWith('/*') || // Block comment start
+      line.includes('Anti-pattern') || // Documentation
+      line.includes('@see') || // JSDoc refs
+      line.includes('@example') // JSDoc examples
+    ) {
+      continue
+    }
+
+    for (const pattern of META_COMMENTARY_PATTERNS) {
+      // Reset lastIndex for global patterns
+      pattern.lastIndex = 0
+
+      let match: RegExpExecArray | null
+      while ((match = pattern.exec(line)) !== null) {
+        violations.push({
+          file: filePath,
+          line: lineNum + 1,
+          column: match.index + 1,
+          match: match[0],
+          pattern: pattern.source,
+        })
+      }
+    }
+  }
+
+  return violations
+}
+
+async function main() {
+  const rootDir = process.cwd()
+  const allViolations: Violation[] = []
+
+  console.log('Checking for meta-commentary patterns...\n')
+
+  for await (const filePath of walkDir(rootDir)) {
+    const violations = await checkFile(filePath)
+    if (violations.length > 0) {
+      allViolations.push(...violations)
+    }
+  }
+
+  if (allViolations.length === 0) {
+    console.log('✅ No meta-commentary patterns found\n')
+    process.exit(0)
+  }
+
+  console.log(`❌ Found ${allViolations.length} meta-commentary violation(s):\n`)
+
+  // Group by file
+  const byFile = new Map<string, Violation[]>()
+  for (const v of allViolations) {
+    const rel = relative(rootDir, v.file)
+    if (!byFile.has(rel)) {
+      byFile.set(rel, [])
+    }
+    byFile.get(rel)!.push(v)
+  }
+
+  for (const [file, violations] of byFile) {
+    console.log(`  ${file}`)
+    for (const v of violations) {
+      console.log(`    ${v.line}:${v.column}  "${v.match}"`)
+    }
+    console.log('')
+  }
+
+  console.log('Fix: Present preferences as facts, not memories.')
+  console.log('  ❌ "I remember you prefer TypeScript"')
+  console.log('  ✅ "Use TypeScript"\n')
+
+  process.exit(1)
+}
+
+main().catch((err) => {
+  console.error('Error:', err.message)
+  process.exit(1)
+})

package/core/services/context-generator.ts

@@ -12,6 +12,7 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import dateHelper from '../utils/date-helper'
+import { mergePreservedSections } from '../utils/preserve-sections'
 
 // ============================================================================
 // TYPES
@@ -180,7 +181,17 @@ Load from \`~/.prjct-cli/projects/${this.config.projectId}/agents/\`:
 **Domain**: ${domainAgents.join(', ') || 'none'}
 `
 
-    await fs.writeFile(path.join(contextPath, 'CLAUDE.md'), content, 'utf-8')
+    // Preserve user customizations from existing file
+    const claudePath = path.join(contextPath, 'CLAUDE.md')
+    let finalContent = content
+    try {
+      const existingContent = await fs.readFile(claudePath, 'utf-8')
+      finalContent = mergePreservedSections(content, existingContent)
+    } catch {
+      // File doesn't exist yet - use generated content as-is
+    }
+
+    await fs.writeFile(claudePath, finalContent, 'utf-8')
   }
 
   /**

package/core/utils/preserve-sections.ts

@@ -0,0 +1,218 @@
+/**
+ * Preserve Sections Utility
+ *
+ * Extracts and preserves user-customized sections during file regeneration.
+ * Users can mark sections with preserve markers to survive sync.
+ *
+ * Usage in CLAUDE.md or other context files:
+ * ```markdown
+ * <!-- prjct:preserve -->
+ * # My Custom Rules
+ * - Always use tabs
+ * - Prefer functional patterns
+ * <!-- /prjct:preserve -->
+ * ```
+ *
+ * @see PRJ-115
+ * @module utils/preserve-sections
+ */
+
+export interface PreservedSection {
+  id: string
+  content: string
+  startIndex: number
+  endIndex: number
+}
+
+// Markers for preserved sections
+const PRESERVE_START = '<!-- prjct:preserve -->'
+const PRESERVE_END = '<!-- /prjct:preserve -->'
+const PRESERVE_END_PATTERN = '<!-- /prjct:preserve -->'
+
+// Named section markers (optional identifier) - create fresh regex each time
+// Uses [\w-]+ to allow hyphens in section names (e.g., "custom-rules")
+function createPreserveStartRegex(): RegExp {
+  return /<!-- prjct:preserve(?::([\w-]+))? -->/g
+}
+
+/**
+ * Extract all preserved sections from content
+ */
+export function extractPreservedSections(content: string): PreservedSection[] {
+  const sections: PreservedSection[] = []
+  const regex = createPreserveStartRegex()
+
+  let match: RegExpExecArray | null
+  let sectionIndex = 0
+
+  while ((match = regex.exec(content)) !== null) {
+    const startIndex = match.index
+    const startTag = match[0]
+    const sectionId = match[1] || `section-${sectionIndex++}`
+
+    // Find the closing tag
+    const endTagStart = content.indexOf(PRESERVE_END_PATTERN, startIndex + startTag.length)
+
+    if (endTagStart === -1) {
+      // No closing tag found - skip this section
+      continue
+    }
+
+    const endIndex = endTagStart + PRESERVE_END_PATTERN.length
+
+    // Extract the content between markers (including markers)
+    const fullContent = content.substring(startIndex, endIndex)
+
+    sections.push({
+      id: sectionId,
+      content: fullContent,
+      startIndex,
+      endIndex,
+    })
+  }
+
+  return sections
+}
+
+/**
+ * Extract the inner content of preserved sections (without markers)
+ */
+export function extractPreservedContent(content: string): string[] {
+  const sections = extractPreservedSections(content)
+
+  return sections.map((section) => {
+    // Remove the markers to get just the inner content
+    let inner = section.content
+    inner = inner.replace(createPreserveStartRegex(), '').replace(PRESERVE_END_PATTERN, '')
+    return inner.trim()
+  })
+}
+
+/**
+ * Check if content has any preserved sections
+ */
+export function hasPreservedSections(content: string): boolean {
+  return content.includes(PRESERVE_START) || createPreserveStartRegex().test(content)
+}
+
+/**
+ * Merge preserved sections from old content into new content
+ *
+ * Strategy:
+ * 1. Extract preserved sections from old content
+ * 2. Append them to the end of new content
+ * 3. Ensure proper spacing
+ *
+ * @param newContent - Freshly generated content
+ * @param oldContent - Previous content with user customizations
+ * @returns Merged content with preserved sections
+ */
+export function mergePreservedSections(newContent: string, oldContent: string): string {
+  const preservedSections = extractPreservedSections(oldContent)
+
+  if (preservedSections.length === 0) {
+    return newContent
+  }
+
+  // Build the merged content
+  let merged = newContent.trimEnd()
+
+  // Add separator before preserved sections
+  merged += '\n\n---\n\n'
+  merged += '## Your Customizations\n\n'
+  merged += '_The sections below are preserved during sync. Edit freely._\n\n'
+
+  // Append each preserved section
+  for (const section of preservedSections) {
+    merged += section.content
+    merged += '\n\n'
+  }
+
+  return merged.trimEnd() + '\n'
+}
+
+/**
+ * Create an empty preserve block for users to customize
+ */
+export function createEmptyPreserveBlock(title?: string): string {
+  const header = title ? `\n# ${title}\n` : '\n'
+  return `${PRESERVE_START}${header}<!-- Add your custom instructions here -->\n${PRESERVE_END}`
+}
+
+/**
+ * Wrap content in preserve markers
+ */
+export function wrapInPreserveMarkers(content: string, id?: string): string {
+  const startTag = id ? `<!-- prjct:preserve:${id} -->` : PRESERVE_START
+  return `${startTag}\n${content}\n${PRESERVE_END}`
+}
+
+/**
+ * Remove all preserved sections from content
+ * (Useful for getting the auto-generated portion only)
+ */
+export function stripPreservedSections(content: string): string {
+  const sections = extractPreservedSections(content)
+
+  if (sections.length === 0) {
+    return content
+  }
+
+  // Remove sections in reverse order to preserve indices
+  let result = content
+  for (let i = sections.length - 1; i >= 0; i--) {
+    const section = sections[i]
+    result = result.substring(0, section.startIndex) + result.substring(section.endIndex)
+  }
+
+  // Clean up any resulting double newlines
+  result = result.replace(/\n{3,}/g, '\n\n')
+
+  return result.trim()
+}
+
+/**
+ * Validate that all preserve blocks are properly closed
+ */
+export function validatePreserveBlocks(content: string): {
+  valid: boolean
+  errors: string[]
+} {
+  const errors: string[] = []
+
+  const startMatches = content.match(/<!-- prjct:preserve(?::\w+)? -->/g) || []
+  const endMatches = content.match(/<!-- \/prjct:preserve -->/g) || []
+
+  if (startMatches.length !== endMatches.length) {
+    errors.push(
+      `Mismatched preserve markers: ${startMatches.length} opening, ${endMatches.length} closing`
+    )
+  }
+
+  // Check for nested blocks (not supported)
+  let depth = 0
+  let maxDepth = 0
+  const lines = content.split('\n')
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (/<!-- prjct:preserve(?::\w+)? -->/.test(line)) {
+      depth++
+      maxDepth = Math.max(maxDepth, depth)
+    }
+    if (line.includes(PRESERVE_END_PATTERN)) {
+      depth--
+    }
+    if (depth > 1) {
+      errors.push(`Nested preserve blocks detected at line ${i + 1} (not supported)`)
+    }
+    if (depth < 0) {
+      errors.push(`Unexpected closing marker at line ${i + 1}`)
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  }
+}

package/dist/bin/prjct.mjs

@@ -12055,7 +12055,7 @@ var init_prompt_builder = __esm({
         try {
           const patterns = await analyzer_default.detectPatterns(projectId);
           if (patterns.length > 0) {
-            parts.push("**Learned Patterns**");
+            parts.push("**Project Conventions**");
             for (const pattern of patterns.slice(0, 3)) {
               parts.push(`- ${pattern.description}`);
               if (pattern.suggestedAction) {
@@ -12315,7 +12315,7 @@ Stack: ${stack}
         }
         parts.push(this.buildCriticalRules());
         if (learnedPatterns && Object.keys(learnedPatterns).some((k) => learnedPatterns[k])) {
-          parts.push("\n## LEARNED PATTERNS (use these, do NOT ask user)\n");
+          parts.push("\n## PROJECT DEFAULTS (apply automatically)\n");
           for (const [key, value] of Object.entries(learnedPatterns)) {
             if (value) {
               parts.push(`- ${key}: ${value}
@@ -12337,7 +12337,7 @@ Stack: ${stack}
 `);
         }
         if (relevantMemories && relevantMemories.length > 0) {
-          parts.push("\n## RELEVANT MEMORIES (apply these learnings)\n");
+          parts.push("\n## CONTEXT (apply these)\n");
           for (const memory of relevantMemories) {
             parts.push(`- **${memory.title}**: ${memory.content}
 `);
@@ -17217,6 +17217,60 @@ var init_formatters = __esm({
   }
 });
 
+// core/utils/preserve-sections.ts
+function createPreserveStartRegex() {
+  return /<!-- prjct:preserve(?::([\w-]+))? -->/g;
+}
+function extractPreservedSections(content) {
+  const sections = [];
+  const regex = createPreserveStartRegex();
+  let match;
+  let sectionIndex = 0;
+  while ((match = regex.exec(content)) !== null) {
+    const startIndex = match.index;
+    const startTag = match[0];
+    const sectionId = match[1] || `section-${sectionIndex++}`;
+    const endTagStart = content.indexOf(PRESERVE_END_PATTERN, startIndex + startTag.length);
+    if (endTagStart === -1) {
+      continue;
+    }
+    const endIndex = endTagStart + PRESERVE_END_PATTERN.length;
+    const fullContent = content.substring(startIndex, endIndex);
+    sections.push({
+      id: sectionId,
+      content: fullContent,
+      startIndex,
+      endIndex
+    });
+  }
+  return sections;
+}
+function mergePreservedSections(newContent, oldContent) {
+  const preservedSections = extractPreservedSections(oldContent);
+  if (preservedSections.length === 0) {
+    return newContent;
+  }
+  let merged = newContent.trimEnd();
+  merged += "\n\n---\n\n";
+  merged += "## Your Customizations\n\n";
+  merged += "_The sections below are preserved during sync. Edit freely._\n\n";
+  for (const section of preservedSections) {
+    merged += section.content;
+    merged += "\n\n";
+  }
+  return merged.trimEnd() + "\n";
+}
+var PRESERVE_END_PATTERN;
+var init_preserve_sections = __esm({
+  "core/utils/preserve-sections.ts"() {
+    "use strict";
+    PRESERVE_END_PATTERN = "<!-- /prjct:preserve -->";
+    __name(createPreserveStartRegex, "createPreserveStartRegex");
+    __name(extractPreservedSections, "extractPreservedSections");
+    __name(mergePreservedSections, "mergePreservedSections");
+  }
+});
+
 // core/ai-tools/registry.ts
 import { execSync as execSync4 } from "node:child_process";
 import fs34 from "node:fs";
@@ -17356,7 +17410,7 @@ async function generateForTool(context2, config, globalPath, repoPath) {
     };
   }
   try {
-    const content = formatter(context2, config);
+    let content = formatter(context2, config);
     let outputPath;
     if (config.outputPath === "repo") {
       outputPath = path38.join(repoPath, config.outputFile);
@@ -17364,6 +17418,11 @@ async function generateForTool(context2, config, globalPath, repoPath) {
       outputPath = path38.join(globalPath, "context", config.outputFile);
     }
     await fs35.mkdir(path38.dirname(outputPath), { recursive: true });
+    try {
+      const existingContent = await fs35.readFile(outputPath, "utf-8");
+      content = mergePreservedSections(content, existingContent);
+    } catch {
+    }
     await fs35.writeFile(outputPath, content, "utf-8");
     return {
       toolId: config.id,
@@ -17384,6 +17443,7 @@ async function generateForTool(context2, config, globalPath, repoPath) {
 var init_generator2 = __esm({
   "core/ai-tools/generator.ts"() {
     "use strict";
+    init_preserve_sections();
     init_formatters();
     init_registry();
     __name(generateAIToolContexts, "generateAIToolContexts");
@@ -17409,6 +17469,7 @@ var init_context_generator = __esm({
   "core/services/context-generator.ts"() {
     "use strict";
     init_date_helper();
+    init_preserve_sections();
     ContextFileGenerator = class {
       static {
         __name(this, "ContextFileGenerator");
@@ -17515,7 +17576,14 @@ Load from \`~/.prjct-cli/projects/${this.config.projectId}/agents/\`:
 **Workflow**: ${workflowAgents.join(", ")}
 **Domain**: ${domainAgents.join(", ") || "none"}
 `;
-        await fs36.writeFile(path39.join(contextPath, "CLAUDE.md"), content, "utf-8");
+        const claudePath = path39.join(contextPath, "CLAUDE.md");
+        let finalContent = content;
+        try {
+          const existingContent = await fs36.readFile(claudePath, "utf-8");
+          finalContent = mergePreservedSections(content, existingContent);
+        } catch {
+        }
+        await fs36.writeFile(claudePath, finalContent, "utf-8");
       }
       /**
        * Generate now.md - current task status
@@ -23330,7 +23398,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "0.45.4",
+      version: "0.46.0",
       description: "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
       main: "core/index.ts",
       bin: {
@@ -23359,6 +23427,7 @@ var require_package = __commonJS({
         validate: "bun scripts/validate-commands.js",
         lint: "biome lint .",
         "lint:fix": "biome lint --write .",
+        "lint:meta": "bun core/cli/lint-meta-commentary.ts",
         format: "biome format --write .",
         "format:check": "biome format .",
         check: "biome check .",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "0.45.4",
+  "version": "0.46.0",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {
@@ -29,6 +29,7 @@
     "validate": "bun scripts/validate-commands.js",
     "lint": "biome lint .",
     "lint:fix": "biome lint --write .",
+    "lint:meta": "bun core/cli/lint-meta-commentary.ts",
     "format": "biome format --write .",
     "format:check": "biome format .",
     "check": "biome check .",