@haposoft/cafekit 0.13.4 → 0.14.0

package/src/claude/scripts/validate-docs.cjs

@@ -53,17 +53,14 @@ function main() {
 
   const linkIssues = checkBrokenLinks(docsDir);
   if (linkIssues.length > 0) {
-    console.warn('\n⚠️ WARNING: CRITICAL HYPERLINK CORRUPTION DETECTED IN DOCUMENTATION MATRIX!');
+    console.error(`\n❌ FAIL: ${linkIssues.length} broken relative link(s) found:`);
     linkIssues.forEach(issue => {
-      console.warn(`- Compromised File: ${path.relative(process.cwd(), issue.file)} -> Links externally to Missing Null Pointer: ./${issue.brokenLink}`);
+      console.error(`- ${path.relative(process.cwd(), issue.file)} -> ./${issue.brokenLink} (target missing)`);
     });
-  } else {
-    console.log('✅ Validation verified! Zero broken integrity links detected across the system.');
+    process.exit(1);
   }
 
-  // Structural Note: To honor Execution Velocity patterns inherent to Architecture,
-  // aggressive deep-code grepping functions (function tracing) have been stripped.
-  // This ensures document validation pipeline triggers definitively under < 1s (Zero-latency verification).
+  console.log('✅ PASS: no broken relative links detected.');
 }
 
 main();

package/src/claude/scripts/validate-spec-output.cjs

@@ -203,11 +203,13 @@ function extractContractDefs(designText) {
 }
 
 /**
- * From a task body, return the contracts it claims plus the first fenced block
- * it carries (the task's local copy of the contract). Shape:
- *   { names: string[], block: string|null }
- * `names` come from a `Contracts: A, B` line; `block` is the first fenced code
- * block in the task (normalized) used to compare against the canonical defs.
+ * From a task body, return the contracts it claims plus its local contract
+ * copies. Shape: { names: string[], blocks: Map<name, string>, firstBlock: string|null }
+ * `names` come from a `Contracts: A, B` line. `blocks` maps every
+ * `<!-- contract:NAME -->` marker in the task to its fenced block, so a task
+ * carrying multiple contracts has EACH copy verified (not just the first).
+ * `firstBlock` keeps the legacy fallback for single-contract tasks that copy
+ * the block without repeating the marker.
  */
 function extractTaskContracts(taskText) {
   const names = [];
@@ -218,9 +220,10 @@ function extractTaskContracts(taskText) {
       if (name) names.push(name);
     }
   }
+  const blocks = extractContractDefs(taskText); // same marker+fence grammar as design.md
   const blockMatch = taskText.match(/```[^\n]*\n([\s\S]*?)\n```/);
-  const block = blockMatch ? normalizeBlock(blockMatch[1]) : null;
-  return { names, block };
+  const firstBlock = blockMatch ? normalizeBlock(blockMatch[1]) : null;
+  return { names, blocks, firstBlock };
 }
 
 function validateSpec(specDir) {
@@ -393,16 +396,33 @@ function validateSpec(specDir) {
     // (after whitespace normalization). This catches BE/FE drift like
     // user_name vs userName before integration.
     if (contractDefs.size > 0) {
-      const { names, block } = extractTaskContracts(content);
+      const { names, blocks, firstBlock } = extractTaskContracts(content);
       for (const name of names) {
         if (!contractDefs.has(name)) {
           errors.push(`${taskFile}: declares unknown contract "${name}" (not defined in design.md)`);
           continue;
         }
-        if (block !== null && block !== contractDefs.get(name)) {
+        // Prefer the task's marker-tagged copy for this contract; fall back to
+        // the first fenced block only for single-contract tasks (legacy format).
+        const localCopy = blocks.has(name)
+          ? blocks.get(name)
+          : (names.length === 1 ? firstBlock : null);
+        if (localCopy === null) {
+          if (names.length > 1) {
+            errors.push(`${taskFile}: contract "${name}" has no <!-- contract:${name} --> tagged block (multi-contract tasks must tag each copy)`);
+          }
+          continue;
+        }
+        if (localCopy !== contractDefs.get(name)) {
           errors.push(`${taskFile}: contract "${name}" body diverges from the canonical definition in design.md`);
         }
       }
+      // Marker-tagged blocks not declared on the Contracts: line are drift risks.
+      for (const taggedName of blocks.keys()) {
+        if (!names.includes(taggedName)) {
+          warnings.push(`${taskFile}: carries <!-- contract:${taggedName} --> block but does not declare it on the Contracts: line`);
+        }
+      }
     }
   }
 

package/src/claude/settings/settings.json

@@ -102,6 +102,10 @@
     "Stop": [
       {
         "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/spec-gate.cjs\""
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state.cjs\""

package/src/claude/skills/ai-multimodal/.env.example

@@ -41,16 +41,16 @@ GEMINI_API_KEY=your_api_key_here
 
 # --- Image Generation ---
 # Used by: --task generate (image)
-# Default: gemini-2.5-flash-image (Nano Banana Flash - fast, cost-effective)
+# Default: gemma-4-31b-it-image (Nano Banana Flash - fast, cost-effective)
 # Alternative: imagen-4.0-generate-001 (production quality)
 # NOTE: All image generation requires billing - no free tier available (limit: 0)
 # Options:
-#   gemini-2.5-flash-image            - Nano Banana Flash: fast, ~$1/1M tokens (DEFAULT)
-#   gemini-3-pro-image-preview        - Nano Banana Pro: 4K text, reasoning (requires billing)
+#   gemma-4-31b-it-image            - Nano Banana Flash: fast, ~$1/1M tokens (DEFAULT)
+#   gemma-4-31b-it-image-preview        - Nano Banana Pro: 4K text, reasoning (requires billing)
 #   imagen-4.0-generate-001           - Imagen 4 Standard: production quality (~$0.02/image)
 #   imagen-4.0-ultra-generate-001     - Imagen 4 Ultra: maximum quality (~$0.04/image)
 #   imagen-4.0-fast-generate-001      - Imagen 4 Fast: speed-optimized (~$0.01/image)
-# IMAGE_GEN_MODEL=gemini-2.5-flash-image
+# IMAGE_GEN_MODEL=gemma-4-31b-it-image
 
 # --- Video Generation ---
 # Used by: --task generate-video (new capability)
@@ -65,17 +65,15 @@ GEMINI_API_KEY=your_api_key_here
 
 # --- Multimodal Analysis ---
 # Used by: --task analyze, transcribe, extract
-# Default: gemini-2.5-flash
+# Default: gemma-4-31b-it
 # Options:
-#   gemini-3-pro-preview           - Latest, agentic workflows, 1M context
-#   gemini-2.5-flash               - Best price/performance (recommended)
-#   gemini-2.5-pro                 - Highest quality
-# MULTIMODAL_MODEL=gemini-2.5-flash
+#   gemma-4-31b-it                 - Best price/performance (recommended)
+# MULTIMODAL_MODEL=gemma-4-31b-it
 
 # --- Legacy Compatibility ---
 # Generic model override (use specific variables above instead)
-# GEMINI_MODEL=gemini-2.5-flash
-# GEMINI_IMAGE_GEN_MODEL=gemini-2.5-flash-image
+# GEMINI_MODEL=gemma-4-31b-it
+# GEMINI_IMAGE_GEN_MODEL=gemma-4-31b-it-image
 
 # ============================================================================
 # MiniMax API Configuration (Optional - for image/video/speech/music generation)
@@ -223,8 +221,8 @@ GEMINI_API_KEY=your_api_key_here
 # 5. Free tier limits: 15 RPM, 1M-4M TPM, 1,500 RPD
 # 6. Vertex AI requires GCP authentication via gcloud CLI
 # 7. Model defaults (Dec 2025):
-#    - Image gen: gemini-2.5-flash-image (Nano Banana Flash - default)
+#    - Image gen: gemma-4-31b-it-image (Nano Banana Flash - default)
 #    - Image gen: imagen-4.0-generate-001 (alternative for production)
 #    - Video gen: veo-3.1-generate-preview
-#    - Analysis: gemini-2.5-flash
+#    - Analysis: gemma-4-31b-it
 # 8. Preview models (veo-3.1, gemini-3) may have API changes

package/src/claude/skills/ai-multimodal/SKILL.md

@@ -43,7 +43,7 @@ export GEMINI_API_KEY_2="key2"  # auto-rotates on rate limit
 ## Models
 
 ### Google Gemini
-- **Analysis**: `gemma-4-31b-it` (recommended), `gemini-2.5-pro` (advanced)
+- **Analysis**: `gemma-4-31b-it` (recommended), `gemma-4-31b-it` (advanced)
 
 ## Scripts
 

package/src/claude/skills/ai-multimodal/references/audio-processing.md

@@ -42,7 +42,7 @@ myfile = client.files.upload(file='meeting.mp3')
 
 # Transcribe
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Generate a transcript of the speech.', myfile]
 )
 print(response.text)
@@ -52,7 +52,7 @@ print(response.text)
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Generate transcript with timestamps in MM:SS format.', myfile]
 )
 ```
@@ -61,7 +61,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Transcribe with speaker labels. Format: [Speaker 1], [Speaker 2], etc.', myfile]
 )
 ```
@@ -70,7 +70,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Transcribe only the segment from 02:30 to 05:15.', myfile]
 )
 ```
@@ -81,7 +81,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Summarize key points in 5 bullets with timestamps.', myfile]
 )
 ```
@@ -91,19 +91,19 @@ response = client.models.generate_content(
 ```python
 # Music analysis
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Identify the musical instruments and genre.', myfile]
 )
 
 # Environmental sounds
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Identify all sounds: voices, music, ambient noise.', myfile]
 )
 
 # Birdsong identification
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Identify bird species based on their calls.', myfile]
 )
 ```
@@ -112,7 +112,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['What is discussed from 10:30 to 15:45? Provide key points.', myfile]
 )
 ```
@@ -127,13 +127,13 @@ myfile = client.files.upload(file='large-audio.mp3')
 
 # First query
 response1 = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Transcribe this', myfile]
 )
 
 # Second query (reuses same file)
 response2 = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Summarize this', myfile]
 )
 ```
@@ -147,7 +147,7 @@ with open('small-audio.mp3', 'rb') as f:
     audio_bytes = f.read()
 
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'Describe this audio',
         types.Part.from_bytes(data=audio_bytes, mime_type='audio/mp3')
@@ -161,14 +161,14 @@ response = client.models.generate_content(
 
 | Model | Quality | Speed | Cost/1M tokens |
 |-------|---------|-------|----------------|
-| `gemini-2.5-flash-native-audio-preview-09-2025` | High | Fast | $10 |
-| `gemini-2.5-pro` TTS mode | Premium | Slower | $20 |
+| `gemma-4-31b-it-native-audio-preview-09-2025` | High | Fast | $10 |
+| `gemma-4-31b-it` TTS mode | Premium | Slower | $20 |
 
 ### Basic TTS
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash-native-audio-preview-09-2025',
+    model='gemma-4-31b-it-native-audio-preview-09-2025',
     contents='Generate audio: Welcome to today\'s episode.'
 )
 
@@ -182,19 +182,19 @@ with open('output.wav', 'wb') as f:
 ```python
 # Professional tone
 response = client.models.generate_content(
-    model='gemini-2.5-flash-native-audio-preview-09-2025',
+    model='gemma-4-31b-it-native-audio-preview-09-2025',
     contents='Generate audio in a professional, clear tone: Welcome to our quarterly earnings call.'
 )
 
 # Casual and friendly
 response = client.models.generate_content(
-    model='gemini-2.5-flash-native-audio-preview-09-2025',
+    model='gemma-4-31b-it-native-audio-preview-09-2025',
     contents='Generate audio in a friendly, conversational tone: Hey there! Let\'s dive into today\'s topic.'
 )
 
 # Narrative style
 response = client.models.generate_content(
-    model='gemini-2.5-flash-native-audio-preview-09-2025',
+    model='gemma-4-31b-it-native-audio-preview-09-2025',
     contents='Generate audio in a narrative, storytelling tone: Once upon a time, in a land far away...'
 )
 ```
@@ -244,9 +244,7 @@ response = client.models.generate_content(
 - 9.5 hours = 1,094,400 tokens
 
 **Model selection**:
-- Use `gemini-2.5-flash` ($1/1M tokens) for most tasks
-- Upgrade to `gemini-2.5-pro` ($3/1M tokens) for complex analysis
-- For high-volume: `gemini-1.5-flash` ($0.70/1M tokens)
+- Use `gemma-4-31b-it` for transcription and analysis (read model from `.claude/runtime.json`: `gemini.model`)
 
 **Reduce costs**:
 - Process only relevant segments using timestamps
@@ -265,7 +263,7 @@ def transcribe_with_retry(file_path, max_retries=3):
         try:
             myfile = client.files.upload(file=file_path)
             response = client.models.generate_content(
-                model='gemini-2.5-flash',
+                model='gemma-4-31b-it',
                 contents=['Transcribe with timestamps', myfile]
             )
             return response.text
@@ -283,7 +281,7 @@ def transcribe_with_retry(file_path, max_retries=3):
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Transcribe this meeting with:
         1. Speaker labels
@@ -299,7 +297,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Create podcast summary with:
         1. Main topics with timestamps
@@ -315,7 +313,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Analyze interview:
         1. Questions asked with timestamps
@@ -331,7 +329,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Verify audio content:
         1. Check for specific keywords or phrases
@@ -348,7 +346,7 @@ response = client.models.generate_content(
 ```python
 # Gemini auto-detects language
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Transcribe this audio and translate to English if needed.', myfile]
 )
 ```

package/src/claude/skills/ai-multimodal/references/video-analysis.md

@@ -22,12 +22,8 @@ Comprehensive guide for video understanding, temporal analysis, and YouTube proc
 
 ## Model Selection
 
-### Gemini 3 Series (Latest)
-- **gemini-3-pro-preview**: Latest, agentic workflows, 1M context, dynamic thinking
-
-### Gemini 2.5 Series (Recommended)
-- **gemini-2.5-pro**: Best quality, 1M-2M context
-- **gemini-2.5-flash**: Balanced, 1M-2M context (recommended)
+### Recommended
+- **gemma-4-31b-it**: 1M-2M context, balanced quality/speed (read model from `.claude/runtime.json`: `gemini.model`)
 
 ### Context Windows
 - **2M token models**: ~2 hours (default) or ~6 hours (low-res)
@@ -57,7 +53,7 @@ if myfile.state.name == 'FAILED':
 
 # Analyze
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Summarize this video in 3 key points', myfile]
 )
 print(response.text)
@@ -69,7 +65,7 @@ print(response.text)
 from google.genai import types
 
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'Summarize the main topics discussed',
         types.Part.from_uri(
@@ -87,7 +83,7 @@ with open('short-clip.mp4', 'rb') as f:
     video_bytes = f.read()
 
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'What happens in this video?',
         types.Part.from_bytes(data=video_bytes, mime_type='video/mp4')
@@ -102,7 +98,7 @@ response = client.models.generate_content(
 ```python
 # Analyze specific time range
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'Summarize this segment',
         types.Part.from_video_metadata(
@@ -119,7 +115,7 @@ response = client.models.generate_content(
 ```python
 # Lower FPS for static content (saves tokens)
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'Analyze this presentation',
         types.Part.from_video_metadata(
@@ -131,7 +127,7 @@ response = client.models.generate_content(
 
 # Higher FPS for fast-moving content
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'Analyze rapid movements in this sports video',
         types.Part.from_video_metadata(
@@ -155,7 +151,7 @@ for video in [video1, video2]:
         video = client.files.get(name=video.name)
 
 response = client.models.generate_content(
-    model='gemini-2.5-pro',
+    model='gemma-4-31b-it',
     contents=[
         'Compare these two product demos. Which explains features better?',
         video1,
@@ -170,7 +166,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'What happens at 01:15 and how does it relate to 02:30?',
         myfile
@@ -182,7 +178,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Create a timeline with timestamps:
         - Key events
@@ -199,7 +195,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'Identify all scene changes with timestamps and describe each scene',
         myfile
@@ -213,7 +209,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'Transcribe the audio from this video',
         myfile
@@ -225,7 +221,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Transcribe with visual context:
         - Audio transcription
@@ -241,7 +237,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'Transcribe with speaker labels and timestamps',
         myfile
@@ -255,7 +251,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Summarize this video:
         1. Main topic and purpose
@@ -271,7 +267,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Create educational materials:
         1. List key concepts taught
@@ -287,7 +283,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'List all actions performed in this tutorial with timestamps',
         myfile
@@ -299,7 +295,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Review video content:
         1. Identify any problematic content
@@ -315,7 +311,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Analyze interview:
         1. Questions asked (timestamps)
@@ -332,7 +328,7 @@ response = client.models.generate_content(
 
 ```python
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         '''Analyze sports video:
         1. Key plays with timestamps
@@ -362,7 +358,7 @@ response = client.models.generate_content(
 youtube_uri = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
 
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=[
         'Create chapter markers with timestamps',
         types.Part.from_uri(uri=youtube_uri, mime_type='video/mp4')
@@ -444,7 +440,7 @@ class VideoAnalysis(BaseModel):
     duration: str
 
 response = client.models.generate_content(
-    model='gemini-2.5-flash',
+    model='gemma-4-31b-it',
     contents=['Analyze this video', myfile],
     config=genai.types.GenerateContentConfig(
         response_mime_type='application/json',