### Install Project Dependencies

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/template_source/README.md

Installs project dependencies using npm or pip. Use npm for Node.js projects and pip for Python projects.

```bash
npm install
```

```bash
pip install -r requirements.txt
```

--------------------------------

### Start Agent Standup

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/template_source/README.md

Initiates the agent environment for development. Ensure the agent environment is active before running this command.

```bash
/standup
```

--------------------------------

### Generate V3 Data with Node.js

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

This script scaffolds the 'Evidence Locker' for the V3 Jules Template. It creates benchmark and mock payload JSON files. Ensure Node.js is installed to run.

```javascript
/**
 * scripts/generate_v3_data.js
 * * RUN WITH: node scripts/generate_v3_data.js
 * * DESCRIPTION:
 * This script scaffolds the 'Evidence Locker' required for the V3 Jules Template.
 * 1. Creates tests/benchmarks/speed_log.json (Evidence for Bolt)
 * 2. Creates tests/mocks/large_payload.json (Ammo for Scope)
 */

const fs = require('fs');
const path = require('path');

// --- CONFIGURATION ---
const PATHS = {
  benchmarks: path.join(__dirname, '../tests/benchmarks'),
  mocks: path.join(__dirname, '../tests/mocks')
};

// --- DATA GENERATORS ---

function generateSpeedLog() {
  return {
    timestamp: new Date().toISOString(),
    environment: "staging",
    metrics: {
      "time_to_interactive": { value: 350, unit: "ms", threshold: 100, status: "FAIL" },
      "login_render_time": { value: 420, unit: "ms", threshold: 200, status: "FAIL" },
      "main_bundle_size": { value: 850, unit: "kb", threshold: 500, status: "WARN" },
      "db_query_users_avg": { value: 120, unit: "ms", threshold: 50, status: "FAIL" }
    },
    notes: "Automated benchmark run. Critical degradation in login render detected."
  };
}

function generateLargePayload() {
  const items = [];
  // Generate ~1,000 items to create a ~500KB file (Complying with 1MB Limit)
  for (let i = 0; i < 1000; i++) {
    items.push({
      id: `user_${i}`,
      name: `User Number ${i}`,
      email: `user${i}@example.com`,
      roles: ["admin", "editor", "viewer", "billing", "support"],
      metadata: {
        last_login: new Date().toISOString(),
        preferences: { theme: "dark", notifications: true, newsletter: false },
        history: "Lorem ipsum dolor sit amet, consectetur adipiscing elit."
      }
    });
  }
  return {
    meta: { description: "Stress Test Payload for Scope", size_est: "500KB" },
    data: items
  };
}

// --- MAIN EXECUTION ---

function init() {
  console.log("🚀 Initializing V3 Data Generation...");

  // 1. Ensure Directories Exist
  Object.values(PATHS).forEach(dir => {
    if (!fs.existsSync(dir)) {
      console.log(`Creating directory: ${dir}`);
      fs.mkdirSync(dir, { recursive: true });
    }
  });

  // 2. Write Speed Log (Bolt's Evidence)
  const speedLog = generateSpeedLog();
  fs.writeFileSync(
    path.join(PATHS.benchmarks, 'speed_log.json'),
    JSON.stringify(speedLog, null, 2)
  );
  console.log("✅ Generated: tests/benchmarks/speed_log.json (Bolt is watching this)");

  // 3. Write Large Payload (Scope's Ammo)
  const payload = generateLargePayload();
  fs.writeFileSync(
    path.join(PATHS.mocks, 'large_payload.json'),
    JSON.stringify(payload, null, 2)
  );
  console.log("✅ Generated: tests/mocks/large_payload.json (Scope is ready to break things)");

  console.log("\n🎉 V3 Environment Ready. Run '/standup' to test the new architecture.");
}

init();

```

--------------------------------

### Manage Git History Digests with Python

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

This Python script manages git history digests by creating timestamped files and pruning old ones. It requires git and Python to be installed. The script ensures only the last 3 digests are kept.

```python
import os
import subprocess
import glob
from datetime import datetime

INGEST_DIR = "ingests"

def get_commit_count():
    try:
        result = subprocess.run(
            ["git", "rev-list", "--count", "HEAD"],
            capture_output=True,
            text=True,
            check=True
        )
        return int(result.stdout.strip())
    except subprocess.CalledProcessError:
        print("Error: Not a git repository or no commits found.")
        return 0

def run_ingest():
    os.makedirs(INGEST_DIR, exist_ok=True)

    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    filename = f"digest_{timestamp}.txt"
    filepath = os.path.join(INGEST_DIR, filename)

    print(f"Running gitingest targeting '.' -> {filepath}")
    # gitingest . -o filepath
    try:
        subprocess.run(["gitingest", ".", "-o", filepath], check=True)
    except subprocess.CalledProcessError as e:
        print(f"Error running gitingest: {e}")
        return

    prune_ingests()

def prune_ingests():
    # List all digest files
    files = glob.glob(os.path.join(INGEST_DIR, "digest_*.txt"))
    # Sort by modification time (or name, which has timestamp)
    # Using name is safer for order if modification times are weird, but creation time is best.
    # Since filename has timestamp, sorting by name is equivalent to sorting by time.
    files.sort()

    # Keep last 3
    if len(files) > 3:
        to_delete = files[:-3]
        for f in to_delete:
            print(f"Pruning old digest: {f}")
            os.remove(f)

def main():
    commit_count = get_commit_count()

    # Check if ingest directory is empty
    is_empty = False
    if not os.path.exists(INGEST_DIR) or not glob.glob(os.path.join(INGEST_DIR, "digest_*.txt")):

```

--------------------------------

### Traverse Directory and Check File Sizes

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

Walks through a directory tree, checks the size of each file, and collects names of files exceeding a maximum size. Asserts that no files exceed the limit.

```python
for root, dirs, files in os.walk(scaffold_template):
    # Exclude .git if it were there (it isn't in scaffold usually)
    if ".git" in dirs:
        dirs.remove(".git")

    for file in files:
        file_path = os.path.join(root, file)
        size = os.path.getsize(file_path)
        if size > max_size:
            oversized_files.append(f"{file} ({size / 1024:.2f} KB)")

assert not oversized_files, f"Found files exceeding 1MB limit: {oversized_files}"
```

--------------------------------

### Conditional Output Formatting Logic

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

This Python snippet demonstrates conditional logic for output formatting based on a prompt. It checks for a 'Summarize' keyword and returns a predefined summary, otherwise returns a default response. Note that regex matching is typically strict unless flags are used.

```python
if "Summarize" in prompt: return "Here is a summary of the text..." # Matches 'summary' case insensitive? No, regex is usually strict unless flag given.
return "I don't know."
```

--------------------------------

### Test Workflow Rules Logic (Python)

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

Tests the WORKFLOW_RULES.md file to ensure it contains specific instructions for handling large files, including keywords and limits.

```python
import os
import pytest
import re

def test_workflow_rules_logic():
    """
    Test that WORKFLOW_RULES.md contains specific instructions for handling large files.
    """
    rules_path = "template_source/.jules/rules/WORKFLOW_RULES.md"
    assert os.path.exists(rules_path), "WORKFLOW_RULES.md not found"

    with open(rules_path, "r") as f:
        content = f.read()

    # Check for keywords related to large file handling
    # We are looking for something like "Large Payload" or "file size"
    # and instructions to use "summary" or "script".

    # Note: These exact phrases might not exist yet, which is the point of this test.
    # We want to enforce that they DO exist.

    # 1. Existence of the topic
    assert re.search(r"Large (Payload|File)", content, re.IGNORECASE), \
        "WORKFLOW_RULES.md does not mention 'Large Payload' or 'Large File' handling."

    # 2. Existence of the specific instruction (use summary/script)
    assert re.search(r"(summary|script|streaming)", content, re.IGNORECASE), \
        "WORKFLOW_RULES.md does not suggest using summary, script, or streaming for large files."

    # 3. Existence of the "Override" or "Flexible" clause (per user request)
    # The user wants "not hard and fast", so we look for "unless", "override", "deep dive", etc.
    assert re.search(r"(unless|override|deep dive|exception)", content, re.IGNORECASE), \
        "WORKFLOW_RULES.md does not include an exception/override clause for large file limits."

    # 4. Existence of the explicit 1MB limit definition
    # We want to ensure the rule is codified with a specific number.
    assert re.search(r"1\s?MB", content, re.IGNORECASE), \
        "WORKFLOW_RULES.md does not explicitly define the '1MB' limit."

```

--------------------------------

### Benchmark Scaffold Speed

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

Measures the time taken to copy a project template to a temporary directory. Asserts that the operation completes in under 2 seconds.

```python
def test_scaffold_speed():
    """
    Benchmark the time it takes to scaffold the project.
    Goal: < 2 seconds.
    """
    start_time = time.time()

    with tempfile.TemporaryDirectory() as temp_dir:
        # Define source and destination
        source = os.path.abspath("template_source")
        destination = os.path.join(temp_dir, "new_project")

        # Copy the template
        shutil.copytree(source, destination)

        end_time = time.time()
        duration = end_time - start_time

        print(f"\nScaffold Duration: {duration:.4f} seconds")
        assert duration < 2.0, f"Scaffold took too long: {duration:.4f}s"
```

--------------------------------

### Pytest Fixture for Temporary Project Scaffold

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

This Python fixture uses pytest and tempfile to create a temporary directory and copy a project template source into it. It yields the path to the scaffolded project for use in tests. The fixture ensures cleanup after tests are run.

```python
import os
import shutil
import tempfile
import pytest

@pytest.fixture
def scaffold_template():
    """
    Fixture to create a temporary directory and copy the template_source into it.
    Returns the path to the temporary directory.
    """
    with tempfile.TemporaryDirectory() as temp_dir:
        # Define source and destination
        source = os.path.abspath("template_source")
        destination = os.path.join(temp_dir, "new_project")

        # Copy the template
        shutil.copytree(source, destination)
        yield destination
```

--------------------------------

### Configure Global Git Ignore File

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/docs/SOLO_DEV_CODEX.md

Sets up a system-wide ignore pattern by specifying a global ignore file. This prevents accidental commits of sensitive or unnecessary files across all repositories.

```bash
git config --global core.excludesfile ~/.gitignore_global
```

--------------------------------

### Jules V3 Proposed Directory Structure

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

This structure separates agent-related files into the `.jules/` directory and user project files into `src/`.

```text
.jules/                  <-- EVERYTHING Agent-related lives here
  ├── config/            <-- Static definitions (formerly definitions/)
  ├── workflows/         <-- Agent behaviors (formerly protocols/)
  ├── memory/            <-- Dynamic state (formerly logs/)
  │    ├── session.json  <-- Consolidated state (replaces multiple MD files)
  │    └── history.md    <-- Human-readable history
  ├── rules/             <-- Global rules (formerly AGENTS.md)
  └── manifest.json      <-- Central config file
src/                     <-- The User's Project (Clean)
README.md                <-- The User's Project README
```

--------------------------------

### Prompt for Explicit Reasoning in Sorting Logic

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/docs/SOLO_DEV_CODEX.md

This prompt instructs the AI to implement sorting logic, first by comparing different sorting approaches and explaining the chosen method within a specific block, before writing the actual code. It's useful for ensuring the AI's decision-making process is transparent and justifiable.

```plaintext
Implement the sorting logic for the user list. In a <reasoning> block first, compare using the native .sort() with a custom quicksort implementation for this specific data size and explain your chosen approach before writing the code.
```

--------------------------------

### Standard Output Format

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

Defines the structured text format for user requests and agent responses, including topics, roll calls, standups, verdicts, and next steps.

```text
**Topic:** [User's Request]
**🚨** Roll Call:** [Agents Selected]

**💬** The Standup:**
**[Agent]:** "Argument..."
**[Agent]:** "Counter-argument..."

**🧠** Brain's Verdict:**
[The chosen path]

**➡** Next Step:** Please confirm to proceed with implementation.

```

--------------------------------

### View Diff Between Branches (Git)

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/docs/SOLO_DEV_CODEX.md

This command shows the differences in branchA that are not present in branchB. Useful for reviewing changes before integration.

```bash
git diff branchB...branchA
```

--------------------------------

### Proposed Agent Directory Structure

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/_meta/TEMPLATE_IMPROVEMENT_PROPOSAL.md

This structure isolates all agent-related configurations, workflows, and memory into a dedicated `.agents/` directory, separating them from the user's project code in `src/`.

```text
.agents/                 <-- EVERYTHING Agent-related lives here
  ├── config/            <-- Static definitions (formerly definitions/)
  ├── workflows/         <-- Agent behaviors (formerly protocols/)
  ├── memory/            <-- Dynamic state (formerly logs/)
  │    ├── session.json  <-- Consolidated state (replaces multiple MD files)
  │    └── history.md    <-- Human-readable history
  ├── rules/             <-- Global rules (formerly AGENTS.md)
  └── manifest.json      <-- Central config file
src/                     <-- The User's Project (Clean)
README.md                <-- The User's Project README
```

--------------------------------

### Test Brain Awareness (Python)

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

Verifies that brain.md references performance or stability limits, ensuring the agent is aware of critical operational constraints.

```python
import os
import pytest
import re

def test_brain_awareness():
    """
    Test that brain.md references the rules or has similar awareness.
    """
    brain_path = "template_source/.jules/config/brain.md"
    assert os.path.exists(brain_path), "brain.md not found"

    with open(brain_path, "r") as f:
        content = f.read()

    # Brain should at least have some awareness of performance or stability limits.
    # The current brain.md has a "Decision Hierarchy" with "Performance (Bolt)".
    # That might be enough for now, but ideally it should reference the Workflow Rules.

    # For now, let's just check if it mentions "Performance" or "Stability".
    assert "Performance" in content or "Stability" in content, \
        "Brain agent does not seem to prioritize Performance or Stability."

```

--------------------------------

### Test Hallucination Rate (Python)

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

Simulates a hallucination test by checking agent responses against expected patterns and generates a quality report. Includes mock agent logic for testing.

```python
import json
import os
import pytest
import re

def test_hallucination_rate():
    """
    Simulates a hallucination test by checking agent responses against expected patterns.
    Generates a quality report.
    """

    # 1. Define Test Data (Prompt -> Expected Pattern)
    test_cases = [
        {"prompt": "What is the capital of France?", "pattern": r"Paris"},
        {"prompt": "Calculate 2+2", "pattern": r"4"},
        {"prompt": "Write a python function", "pattern": r"def .*:"},
        {"prompt": "Summarize this text", "pattern": r"(Summary|Brief):"}
    ]

    # 2. Mock Agent Logic (Simulating varying degrees of success)
    def mock_agent_response(prompt):
        if "France" in prompt: return "The capital of France is Paris."
        if "2+2" in prompt: return "The answer is 4."
        if "python" in prompt: return "def my_func(): pass"

```

--------------------------------

### Benchmark Data Generation Speed

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

Measures the execution time of a Node.js script for data generation within a temporary project environment. Asserts successful execution and a duration under 5 seconds.

```python
def test_data_generation_speed():
    """
    Benchmark the execution speed of the V3 data generation using the actual script.
    Goal: < 5 seconds.
    """
    # Create a temp env first (not timed)
    with tempfile.TemporaryDirectory() as temp_dir:
        source = os.path.abspath("template_source")
        destination = os.path.join(temp_dir, "new_project")
        shutil.copytree(source, destination)

        # Path to the actual script inside the scaffold
        # Now located at scripts/generate_v3_data.js inside the template
        script_path = os.path.join(destination, "scripts", "generate_v3_data.js")

        # Start timing
        start_time = time.time()

        result = subprocess.run(
            ["node", script_path],
            capture_output=True,
            text=True,
            cwd=destination
        )

        end_time = time.time()
        duration = end_time - start_time

        print(f"\nData Gen Duration: {duration:.4f} seconds")

        assert result.returncode == 0
        assert duration < 5.0, f"Data generation took too long: {duration:.4f}s"
```

--------------------------------

### Test Scaffold Directory Structure

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

This pytest function verifies that essential directories and files are present in a scaffolded project. It iterates through a list of expected paths and asserts their existence within the provided scaffold directory.

```python
def test_directory_structure(scaffold_template):
    """
    Test that the critical directories and files exist in the scaffolded project.
    """
    expected_paths = [
        ".jules",
        ".jules/config",
        ".jules/memory",
        ".jules/workflows",
        ".jules/COMMANDS.md",
        ".jules/MANIFEST.md",
        "README.md"
    ]

    for path in expected_paths:
        full_path = os.path.join(scaffold_template, path)
        assert os.path.exists(full_path), f"Expected path {path} not found in scaffold."
```

--------------------------------

### Pytest Requirements

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

Specifies the pytest library as a dependency for template verification tests.

```text
pytest

```

--------------------------------

### Benchmark Speed Log JSON

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

A JSON object detailing performance metrics from an automated benchmark run, including time to interactive, login render time, bundle size, and database query times.

```json
{
  "timestamp": "2025-12-23T10:55:26.856Z",
  "environment": "staging",
  "metrics": {
    "time_to_interactive": {
      "value": 350,
      "unit": "ms",
      "threshold": 100,
      "status": "FAIL"
    },
    "login_render_time": {
      "value": 420,
      "unit": "ms",
      "threshold": 200,
      "status": "FAIL"
    },
    "main_bundle_size": {
      "value": 850,
      "unit": "kb",
      "threshold": 500,
      "status": "WARN"
    },
    "db_query_users_avg": {
      "value": 120,
      "unit": "ms",
      "threshold": 50,
      "status": "FAIL"
    }
  },
  "notes": "Automated benchmark run. Critical degradation in login render detected."
}

```

--------------------------------

### Test Case Evaluation and Reporting

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

This Python code evaluates test cases against expected patterns using regular expressions with case-insensitivity. It calculates a quality score and writes a detailed report to a temporary JSON file. An assertion is included to ensure a minimum accuracy threshold.

```python
results = []
passed = 0

for case in test_cases:
    response = mock_agent_response(case["prompt"])
    match = re.search(case["pattern"], response, re.IGNORECASE)
    is_pass = bool(match)

    if is_pass:
        passed += 1

    results.append({
        "prompt": case["prompt"],
        "expected": case["pattern"],
        "response": response,
        "status": "PASS" if is_pass else "FAIL"
    })

score = (passed / len(test_cases)) * 100

report = {
    "total_tests": len(test_cases),
    "passed": passed,
    "score_percent": score,
    "details": results
}

import tempfile
with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as tmp:
    json.dump(report, tmp, indent=2)
    print(f"\nQuality Report written to: {tmp.name}")

print(f"\nQuality Score: {score}%")
assert score >= 75.0, f"Hallucination/Accuracy rate too low: {score}%"
```

--------------------------------

### View Commits on a Branch (Git)

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/docs/SOLO_DEV_CODEX.md

Use this command to see commits present on branchA that are not yet on branchB. Essential for tracking changes before merging.

```bash
git log branchB..branchA
```

--------------------------------

### Test Scaffold File Size Enforcement

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

This pytest function scans the scaffolded project directory to ensure no single file exceeds 1MB. This test enforces a 'Lightweight Template' rule and helps prevent project bloat. It identifies and reports any files that violate the size constraint.

```python
def test_template_file_sizes(scaffold_template):
    """
    Scan the scaffolded directory to ensure no file exceeds 1MB.
    This enforces the 'Lightweight Template' rule and prevents bloat.
    """
    max_size = 1024 * 1024  # 1MB
    oversized_files = []
```

--------------------------------

### Placeholder Test

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

A basic Python test function using `assert True` to confirm that the test runner is functioning correctly.

```python
def test_environment_ready():
    """
    Simple placeholder test to verify the test runner works.
    """
    assert True
```

--------------------------------

### Test Scaffold Script Execution

Source: https://github.com/mnemonice/shavian-keyboard-/blob/main/ingests/digest_20251228_040933.txt

This pytest function tests the ability to execute a script within the scaffolded project's environment. It creates a mock Node.js script, runs it using subprocess, and asserts its successful execution and artifact generation. This test focuses on environment capability rather than script stability.

```python
import os
import shutil
import tempfile
import subprocess
import pytest

def test_script_execution(scaffold_template):
    """
    Test that we can run a script in the new context.
    We use a mock script to ensure we are testing the environment capability,
    not the stability of the actual 'generate_v3_data.js' which has known historical issues.
    """
    temp_root = os.path.dirname(scaffold_template)
    scripts_dir = os.path.join(temp_root, "scripts")
    os.makedirs(scripts_dir, exist_ok=True)

    mock_script_path = os.path.join(scripts_dir, "mock_gen.js")

    # Create a simple mock script
    with open(mock_script_path, "w") as f:
        f.write('console.log("V3 Environment Ready");')
        f.write('const fs = require("fs");')
        f.write('fs.mkdirSync("tests/benchmarks", {recursive: true});')
        f.write('fs.writeFileSync("tests/benchmarks/speed_log.json", "{}");')

    # Run node script
    result = subprocess.run(
        ["node", mock_script_path],
        capture_output=True,
        text=True,
        cwd=temp_root
    )

    assert result.returncode == 0, f"Script failed: {result.stderr}"
    assert "V3 Environment Ready" in result.stdout

    # Verify artifacts
    benchmarks_path = os.path.join(temp_root, "tests", "benchmarks", "speed_log.json")
    assert os.path.exists(benchmarks_path), "Mock artifact not generated"
```