prjct-cli 1.10.0 → 1.12.0

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/schemas/state.ts

@@ -44,11 +44,18 @@ export const SubtaskSummarySchema = z.object({
       action: z.enum(['created', 'modified', 'deleted']),
     })
   ),
-  whatWasDone: z.array(z.string()),
-  outputForNextAgent: z.string().optional(),
+  whatWasDone: z.array(z.string()).min(1),
+  outputForNextAgent: z.string().min(1),
   notes: z.string().optional(),
 })
 
+// Schema for validating completion data before persisting
+// Used by completeSubtask() to enforce mandatory handoff
+export const SubtaskCompletionDataSchema = z.object({
+  output: z.string().min(1, 'Subtask output is required'),
+  summary: SubtaskSummarySchema,
+})
+
 // Subtask schema for task fragmentation
 export const SubtaskSchema = z.object({
   id: z.string(), // subtask-xxx
@@ -169,6 +176,7 @@ export type ActivityType = z.infer<typeof ActivityTypeSchema>
 
 export type Subtask = z.infer<typeof SubtaskSchema>
 export type SubtaskSummary = z.infer<typeof SubtaskSummarySchema>
+export type SubtaskCompletionData = z.infer<typeof SubtaskCompletionDataSchema>
 export type SubtaskProgress = z.infer<typeof SubtaskProgressSchema>
 
 export type CurrentTask = z.infer<typeof CurrentTaskSchema>
@@ -197,6 +205,18 @@ export const parseQueue = (data: unknown): QueueJson => QueueJsonSchema.parse(da
 export const safeParseState = (data: unknown) => StateJsonSchema.safeParse(data)
 export const safeParseQueue = (data: unknown) => QueueJsonSchema.safeParse(data)
 
+/** Validate subtask completion data — returns errors or null */
+export const validateSubtaskCompletion = (
+  data: unknown
+): { success: true; data: SubtaskCompletionData } | { success: false; errors: string[] } => {
+  const result = SubtaskCompletionDataSchema.safeParse(data)
+  if (result.success) return { success: true, data: result.data }
+  return {
+    success: false,
+    errors: result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+  }
+}
+
 // =============================================================================
 // Defaults
 // =============================================================================

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
   // ==========================================================================

package/core/storage/analysis-storage.ts

@@ -0,0 +1,328 @@
+/**
+ * Analysis Storage (PRJ-263)
+ *
+ * Manages sealable analysis with dual storage:
+ * - storage/analysis.json       (current draft)
+ * - storage/analysis-sealed.json (locked sealed version)
+ *
+ * Lifecycle: DRAFT → VERIFIED → SEALED
+ * Re-sync creates a new draft WITHOUT destroying the sealed version.
+ * Only sealed analysis feeds task context.
+ */
+
+import { createHash } from 'node:crypto'
+import type { AnalysisSchema } from '../schemas/analysis'
+import { AnalysisItemSchema } from '../schemas/analysis'
+import { getTimestamp } from '../utils/date-helper'
+import { StorageManager } from './storage-manager'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface AnalysisStoreData {
+  draft: AnalysisSchema | null
+  sealed: AnalysisSchema | null
+  lastUpdated: string
+}
+
+interface SealResult {
+  success: boolean
+  signature?: string
+  error?: string
+}
+
+interface StalenessCheck {
+  isStale: boolean
+  sealedCommit: string | null
+  currentCommit: string | null
+  message: string
+}
+
+// =============================================================================
+// Analysis Storage
+// =============================================================================
+
+class AnalysisStorage extends StorageManager<AnalysisStoreData> {
+  constructor() {
+    super('analysis.json')
+  }
+
+  protected getDefault(): AnalysisStoreData {
+    return {
+      draft: null,
+      sealed: null,
+      lastUpdated: '',
+    }
+  }
+
+  protected getMdFilename(): string {
+    return 'analysis.md'
+  }
+
+  protected getLayer(): string {
+    return 'analysis'
+  }
+
+  protected getEventType(action: 'update' | 'create' | 'delete'): string {
+    return `analysis.${action}d`
+  }
+
+  protected toMarkdown(data: AnalysisStoreData): string {
+    const lines = ['# Analysis Status', '']
+
+    // Show sealed analysis if available
+    if (data.sealed) {
+      lines.push('## Sealed Analysis')
+      lines.push(`- **Status**: sealed`)
+      lines.push(`- **Commit**: \`${data.sealed.commitHash || 'unknown'}\``)
+      lines.push(`- **Sealed at**: ${data.sealed.sealedAt || 'unknown'}`)
+      lines.push(`- **Languages**: ${data.sealed.languages.join(', ') || 'none'}`)
+      lines.push(`- **Frameworks**: ${data.sealed.frameworks.join(', ') || 'none'}`)
+      lines.push(`- **Files**: ${data.sealed.fileCount}`)
+      if (data.sealed.patterns.length > 0) {
+        lines.push(`- **Patterns**: ${data.sealed.patterns.map((p) => p.name).join(', ')}`)
+      }
+      lines.push('')
+    }
+
+    // Show draft if different from sealed
+    if (data.draft && data.draft.status === 'draft') {
+      lines.push('## Draft Analysis')
+      lines.push(`- **Status**: draft (not yet sealed)`)
+      lines.push(`- **Commit**: \`${data.draft.commitHash || 'unknown'}\``)
+      lines.push(`- **Analyzed at**: ${data.draft.analyzedAt}`)
+      lines.push(`- **Languages**: ${data.draft.languages.join(', ') || 'none'}`)
+      lines.push(`- **Frameworks**: ${data.draft.frameworks.join(', ') || 'none'}`)
+      lines.push(`- **Files**: ${data.draft.fileCount}`)
+      lines.push('')
+    }
+
+    if (!data.sealed && !data.draft) {
+      lines.push('_No analysis available. Run `p. sync` to generate._')
+      lines.push('')
+    }
+
+    return lines.join('\n')
+  }
+
+  // ===========================================================================
+  // Domain Methods
+  // ===========================================================================
+
+  /**
+   * Save a new draft analysis (called by sync-service).
+   * Preserves existing sealed analysis.
+   */
+  async saveDraft(projectId: string, analysis: AnalysisSchema): Promise<void> {
+    const draft: AnalysisSchema = {
+      ...analysis,
+      status: 'draft',
+    }
+
+    // Validate with Zod
+    AnalysisItemSchema.parse(draft)
+
+    await this.update(projectId, (data) => ({
+      ...data,
+      draft,
+      lastUpdated: getTimestamp(),
+    }))
+
+    await this.publishEntityEvent(projectId, 'analysis', 'drafted', {
+      commitHash: draft.commitHash,
+      fileCount: draft.fileCount,
+    })
+  }
+
+  /**
+   * Seal the current draft analysis.
+   * Computes SHA-256 signature and locks the analysis.
+   */
+  async seal(projectId: string): Promise<SealResult> {
+    const data = await this.read(projectId)
+
+    if (!data.draft) {
+      return { success: false, error: 'No draft analysis to seal. Run `p. sync` first.' }
+    }
+
+    if (data.draft.status === 'sealed') {
+      return { success: false, error: 'Draft is already sealed.' }
+    }
+
+    // Compute signature
+    const signature = this.computeSignature(data.draft)
+    const now = getTimestamp()
+
+    const sealed: AnalysisSchema = {
+      ...data.draft,
+      status: 'sealed',
+      signature,
+      sealedAt: now,
+    }
+
+    // Validate
+    AnalysisItemSchema.parse(sealed)
+
+    await this.write(projectId, {
+      draft: null, // Clear draft — it's now sealed
+      sealed,
+      lastUpdated: now,
+    })
+
+    await this.publishEntityEvent(projectId, 'analysis', 'sealed', {
+      commitHash: sealed.commitHash,
+      signature,
+    })
+
+    return { success: true, signature }
+  }
+
+  /**
+   * Get the sealed analysis (for task context injection).
+   * Returns null if no sealed analysis exists.
+   */
+  async getSealed(projectId: string): Promise<AnalysisSchema | null> {
+    const data = await this.read(projectId)
+    return data.sealed
+  }
+
+  /**
+   * Get the current draft analysis.
+   */
+  async getDraft(projectId: string): Promise<AnalysisSchema | null> {
+    const data = await this.read(projectId)
+    return data.draft
+  }
+
+  /**
+   * Get the active analysis (sealed if available, otherwise draft).
+   * This is what tasks should consume.
+   */
+  async getActive(projectId: string): Promise<AnalysisSchema | null> {
+    const data = await this.read(projectId)
+    return data.sealed ?? data.draft
+  }
+
+  /**
+   * Get the current analysis status.
+   */
+  async getStatus(projectId: string): Promise<{
+    hasSealed: boolean
+    hasDraft: boolean
+    sealedCommit: string | null
+    draftCommit: string | null
+    sealedAt: string | null
+  }> {
+    const data = await this.read(projectId)
+    return {
+      hasSealed: data.sealed !== null,
+      hasDraft: data.draft !== null,
+      sealedCommit: data.sealed?.commitHash ?? null,
+      draftCommit: data.draft?.commitHash ?? null,
+      sealedAt: data.sealed?.sealedAt ?? null,
+    }
+  }
+
+  /**
+   * Check if sealed analysis is stale (commit hash differs from current HEAD).
+   */
+  checkStaleness(sealedCommit: string | null, currentCommit: string | null): StalenessCheck {
+    if (!sealedCommit) {
+      return {
+        isStale: false,
+        sealedCommit: null,
+        currentCommit,
+        message: 'No sealed analysis. Run `p. sync` then `p. seal`.',
+      }
+    }
+
+    if (!currentCommit) {
+      return {
+        isStale: true,
+        sealedCommit,
+        currentCommit: null,
+        message: 'Cannot determine current commit. Analysis may be stale.',
+      }
+    }
+
+    if (sealedCommit !== currentCommit) {
+      return {
+        isStale: true,
+        sealedCommit,
+        currentCommit,
+        message: `Analysis is stale: sealed at ${sealedCommit}, HEAD is ${currentCommit}. Run \`p. sync\` + \`p. seal\` to update.`,
+      }
+    }
+
+    return {
+      isStale: false,
+      sealedCommit,
+      currentCommit,
+      message: 'Analysis is current.',
+    }
+  }
+
+  /**
+   * Verify the integrity of a sealed analysis by recomputing its signature.
+   */
+  async verify(projectId: string): Promise<{ valid: boolean; message: string }> {
+    const data = await this.read(projectId)
+
+    if (!data.sealed) {
+      return { valid: false, message: 'No sealed analysis to verify.' }
+    }
+
+    if (!data.sealed.signature) {
+      return { valid: false, message: 'Sealed analysis has no signature.' }
+    }
+
+    const expected = this.computeSignature({
+      ...data.sealed,
+      // Strip signature and sealedAt before recomputing — they weren't part of the original hash
+      signature: undefined,
+      sealedAt: undefined,
+    })
+
+    if (expected === data.sealed.signature) {
+      return { valid: true, message: 'Signature verified. Analysis integrity confirmed.' }
+    }
+
+    return {
+      valid: false,
+      message: `Signature mismatch. Expected ${expected}, got ${data.sealed.signature}. Analysis may have been modified.`,
+    }
+  }
+
+  // ===========================================================================
+  // Private Helpers
+  // ===========================================================================
+
+  /**
+   * Compute SHA-256 signature for analysis data.
+   * Deterministic: same input always produces same hash.
+   */
+  private computeSignature(analysis: AnalysisSchema): string {
+    // Build a canonical representation (exclude volatile fields)
+    const canonical = {
+      projectId: analysis.projectId,
+      languages: analysis.languages,
+      frameworks: analysis.frameworks,
+      packageManager: analysis.packageManager,
+      sourceDir: analysis.sourceDir,
+      testDir: analysis.testDir,
+      configFiles: analysis.configFiles,
+      fileCount: analysis.fileCount,
+      patterns: analysis.patterns,
+      antiPatterns: analysis.antiPatterns,
+      analyzedAt: analysis.analyzedAt,
+      commitHash: analysis.commitHash,
+    }
+
+    return createHash('sha256').update(JSON.stringify(canonical)).digest('hex')
+  }
+}
+
+export const analysisStorage = new AnalysisStorage()
+export default analysisStorage
+export type { AnalysisStoreData, SealResult, StalenessCheck }

package/core/storage/index.ts

@@ -55,6 +55,8 @@ export type {
   ShippedJson,
   Storage,
 } from '../types'
+export type { AnalysisStoreData, SealResult, StalenessCheck } from './analysis-storage'
+export { analysisStorage } from './analysis-storage'
 export { ideasStorage } from './ideas-storage'
 export type {
   CategoriesCache,