Version Logger

EVERY ACTION MUST BEGIN with an ACTION_LOG entry before any work is performed:

{
  "action_log_entry": {
    "timestamp": "2026-03-22T14:32:18Z",
    "action_id": "550e8400-e29b-41d4-a716-446655440000",
    "skill_invoked": "data-processor",
    "action_type": "MODIFY",
    "target_files": [
      "/path/to/file1.py",
      "/path/to/file2.json"
    ],
    "pre_state_hash": {
      "/path/to/file1.py": "a3c4e8f2b1d9c7a5f3e1b8d6c4a2f9e7",
      "/path/to/file2.json": "f7e5c3a1d9b7f5e3c1a9b7d5f3e1c9a7"
    },
    "description": "Update data processing logic to handle edge cases",
    "version": "1.2.3",
    "project": "Lease Audit System",
    "expected_changes": {
      "lines_added_min": 5,
      "lines_added_max": 50,
      "functions_added": ["validate_edge_cases"],
      "functions_modified": ["process_data"]
    }
  }
}

EVERY ACTION MUST END with completion verification:

{
  "action_log_completion": {
    "action_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-03-22T14:33:45Z",
    "status": "SUCCESS",
    "duration_seconds": 87,
    "post_state_hash": {
      "/path/to/file1.py": "b4d5f9g3c2e8a4f1b0d7c5e3a1f9b8d6",
      "/path/to/file2.json": "g8f6d4b2e0c8a6f4d2b0e8c6a4f2d0b8"
    },
    "changes_summary": "Added validate_edge_cases function, modified process_data error handling",
    "lines_added": 23,
    "lines_removed": 5,
    "functions_added": ["validate_edge_cases"],
    "functions_modified": ["process_data"],
    "qa_gate_result": "PASS",
    "errors": [],
    "warnings": [],
    "hallucination_check": {
      "files_exist": true,
      "functions_exist": true,
      "line_count_valid": true,
      "syntax_valid": true,
      "claims_vs_actual": "MATCH"
    }
  }
}

3. Roadmap Version Control

Every orchestration session updates ROADMAP.json:

{
  "project": "Lease Audit System",
  "version": "1.2.3",
  "session_id": "550e8400-e29b-41d4-a716-446655440001",
  "session_started": "2026-03-22T14:00:00Z",
  "workstreams": [
    {
      "ws_id": "WS-2024-001",
      "title": "Data Processing Pipeline",
      "description": "Implement and test ETL pipeline for lease data",
      "status": "IN_PROGRESS",
      "skill_used": "data-processor",
      "qa_result": "PASS",
      "completed_timestamp": null,
      "actions": ["550e8400-e29b-41d4-a716-446655440000"]
    },
    {
      "ws_id": "WS-2024-002",
      "title": "Validation Rules",
      "description": "Add edge case validation",
      "status": "COMPLETED",
      "skill_used": "validator",
      "qa_result": "PASS",
      "completed_timestamp": "2026-03-22T13:45:00Z",
      "actions": ["550e8400-e29b-41d4-a716-446655440002"]
    }
  ],
  "version_history": [
    {
      "version": "1.2.2",
      "timestamp": "2026-03-21T17:00:00Z",
      "changes": "Initial validation rules"
    },
    {
      "version": "1.2.3",
      "timestamp": "2026-03-22T14:00:00Z",
      "changes": "Edge case handling improvements"
    }
  ]
}

4. Hallucination Detection Protocol (8-Point Check)

After every action, this skill MUST perform these checks:

4.1 File Existence Check

# Verify all claimed created/modified files actually exist on disk
for file in "${files_claimed[@]}"; do
  if [ ! -f "$file" ]; then
    HALLUCINATION_FLAG="PHANTOM_FILE: $file claimed but not found"
  fi
done

4.2 Function Existence Check

# Verify all claimed added/modified functions exist in files
for func in "${functions_claimed[@]}"; do
  if ! grep -q "def $func\|function $func\|func $func" "$target_file"; then
    HALLUCINATION_FLAG="PHANTOM_FUNCTION: $func claimed but not found"
  fi
done

4.3 Line Count Validation (±5% tolerance)

# Pre: 100 lines, claimed added: 20 (should be 115-125)
# If post count is 105 or 135+, flag mismatch
diff_lines=$((post_count - pre_count))
tolerance=$((expected_added_lines / 20))  # 5%
if [ $diff_lines -lt $((expected_added_lines - tolerance)) ] || \
   [ $diff_lines -gt $((expected_added_lines + tolerance)) ]; then
  HALLUCINATION_FLAG="LINE_COUNT_MISMATCH"
fi

4.4 Syntax Balance Check

# Count braces, brackets, parentheses - should be balanced
open_braces=$(grep -o '{' "$file" | wc -l)
close_braces=$(grep -o '}' "$file" | wc -l)
if [ $open_braces -ne $close_braces ]; then
  HALLUCINATION_FLAG="SYNTAX_IMBALANCE: braces mismatch"
fi
# Repeat for [ ] and ( )

4.5 SHA-256 Hash Verification

# Compute SHA-256 before and after
# If pre_hash == post_hash and claimed changes != empty, hallucination
# If pre_hash != post_hash and claimed changes == empty, hallucination
sha256sum_pre=$(sha256sum "$file" | awk '{print $1}')
sha256sum_post=$(sha256sum "$file" | awk '{print $1}')

4.6 Diff Summary Cross-Check

# Run actual git diff or text diff
# Compare actual diff against claimed "changes_summary"
# If claims include functions that don't appear in diff, flag it
actual_diff=$(diff -u "$file.bak" "$file" | head -20)

4.7 Git Log Verification

# If git repo exists, verify git commit matches action log
# Verify committed changes match logged changes
git show --stat HEAD | grep "$target_file"

4.8 Domain QA Gate Script

# Run project-specific QA gate script if it exists
# e.g., for Python: pylint, flake8, mypy
# For JSON: jq validation
# For SQL: syntax check
if [ -f "qa-gates/check-$domain.sh" ]; then
  ./qa-gates/check-$domain.sh "$file"
fi

5. Session Log Format

Every orchestration session produces a complete SESSION_LOG.json:

{
  "session_log": {
    "session_id": "550e8400-e29b-41d4-a716-446655440001",
    "started": "2026-03-22T14:00:00Z",
    "ended": "2026-03-22T14:45:30Z",
    "project": "Lease Audit System",
    "initial_version": "1.2.2",
    "final_version": "1.2.3",
    "actions_performed": 5,
    "actions": [
      "550e8400-e29b-41d4-a716-446655440000",
      "550e8400-e29b-41d4-a716-446655440002"
    ],
    "qa_gates": {
      "total_run": 10,
      "passed": 10,
      "failed": 0,
      "skipped": 0,
      "failure_details": []
    },
    "hallucination_checks": {
      "total_checks": 40,
      "flags": 0,
      "false_positives": 0,
      "issues": []
    },
    "files_modified": [
      {
        "path": "/path/to/file1.py",
        "pre_hash": "a3c4e8f2b1d9c7a5f3e1b8d6c4a2f9e7",
        "post_hash": "b4d5f9g3c2e8a4f1b0d7c5e3a1f9b8d6",
        "lines_added": 23,
        "lines_removed": 5,
        "status": "VERIFIED"
      }
    ],
    "summary": {
      "total_lines_added": 47,
      "total_lines_removed": 12,
      "net_lines_added": 35,
      "functions_added": 3,
      "functions_modified": 8,
      "duration_minutes": 45,
      "success_rate": "100%",
      "no_hallucinations_detected": true
    },
    "recommendations": [],
    "next_steps": []
  }
}

6. Error Recovery & Rollback

If any QA gate fails or hallucination is detected:

1. Log the failure in KNOWN_ISSUES.json with:

   • Issue ID (UUID)
   • Timestamp
   • Description
   • Severity (CRITICAL | HIGH | MEDIUM | LOW)
   • Suggested resolution
   • Status (OPEN | INVESTIGATING | RESOLVED)

2. Trigger re-verification:

   • Re-run hallucination checks with increased verbosity
   • Collect additional diagnostic info (git log, file system state)
   • Generate detailed error report

3. Support rollback:

   • Every action's pre_state_hash allows byte-for-byte rollback
   • Maintain action history for forensic analysis
   • Never delete logs (append-only audit trail)

Example KNOWN_ISSUES.json:

{
  "known_issues": [
    {
      "issue_id": "550e8400-e29b-41d4-a716-446655440099",
      "action_id": "550e8400-e29b-41d4-a716-446655440000",
      "timestamp": "2026-03-22T14:33:45Z",
      "title": "Line count mismatch in file1.py",
      "description": "Claimed 20 lines added but only 15 actually added",
      "severity": "MEDIUM",
      "resolution": "Re-verify function implementation, check for unintended deletions",
      "status": "OPEN",
      "action_taken": null
    }
  ]
}

7. Version Management

Versions follow semver: MAJOR.MINOR.PATCH

• MAJOR: Breaking API changes, major feature additions
• MINOR: Feature additions, backwards-compatible improvements
• PATCH: Bug fixes, minor improvements

Every action must include and update the current version. Before actions that modify multiple systems, increment MINOR. Before patch fixes, increment PATCH.

8. Meta-QA Gates (QA for the QA system itself)

8.1 Pre-Action Gate

Runs BEFORE any action:

1. Verify log file exists at expected location
2. Verify version is current and valid semver
3. Verify all pre-state hashes are computed
4. Verify action_id is valid UUID
5. Verify target files are readable
6. Verify action description is non-empty and specific
7. Verify expected_changes object exists
8. Verify action_type is valid enum
9. Verify timestamp is current
10. Verify skill_invoked matches caller

8.2 Post-Action Gate

Runs AFTER every action:

1. Verify post-state hashes computed
2. Verify all target files still exist
3. Verify actual changes match within tolerance
4. Verify no hallucination flags
5. Verify status is valid enum
6. Verify completion timestamp is after start
7. Verify duration_seconds is positive
8. Verify all QA checks passed
9. Verify git commit exists (if applicable)
10. Verify log file was appended

8.3 Session Gate

Runs at session end:

1. Verify all actions were logged
2. Verify all QA gate results recorded
3. Verify roadmap updated
4. Verify final version incremented appropriately
5. Verify no orphaned logs
6. Verify total duration is reasonable
7. Verify success metrics match action count
8. Verify hallucination checks all completed
9. Verify KNOWN_ISSUES updated if needed
10. Verify session log is valid JSON

9. Usage Examples

Starting an Action

./scripts/version-log.sh start \
  "Add validation for lease payment data" \
  /path/to/validator.py \
  /path/to/schemas.json

Returns:

ACTION_ID=550e8400-e29b-41d4-a716-446655440000
PRE_HASH_validator.py=a3c4e8f2b1d9c7a5f3e1b8d6c4a2f9e7
PRE_HASH_schemas.json=f7e5c3a1d9b7f5e3c1a9b7d5f3e1c9a7

Completing an Action

./scripts/version-log.sh end \
  550e8400-e29b-41d4-a716-446655440000 \
  SUCCESS \
  "Added validate_payment_fields function"

Returns:

POST_HASH_validator.py=b4d5f9g3c2e8a4f1b0d7c5e3a1f9b8d6
LINES_ADDED=18
LINES_REMOVED=2
FUNCTIONS_ADDED=validate_payment_fields
HALLUCINATION_CHECK=PASS
QA_GATE_RESULT=PASS

Verifying Changes

./scripts/version-log.sh verify 550e8400-e29b-41d4-a716-446655440000

Querying Session Log

./scripts/version-log.sh query-session 550e8400-e29b-41d4-a716-446655440001

Rollback to Checkpoint

./scripts/version-log.sh rollback 550e8400-e29b-41d4-a716-446655440000

10. Integration with CI/CD

This skill MUST be invoked:

• Before deployment pipelines
• Before code merges
• After significant code changes
• At every QA gate checkpoint
• During rollback procedures
• In error recovery workflows

Example GitHub Actions integration:

- name: Version Log - Pre-Action
  run: ./scripts/version-log.sh start "Deploy to staging" app.py

- name: Run Tests
  run: npm test

- name: Version Log - Post-Action
  run: ./scripts/version-log.sh end ${{ env.ACTION_ID }} SUCCESS "Tests passed"

- name: Version Log - QA Gate
  run: ./scripts/version-log.sh qa-check

11. Critical Rules (INVIOLABLE)

1. EVERY action must be logged - No exceptions, no shortcuts
2. All hashes must be verified - Before and after every change
3. Hallucination checks must pass - All 8 points, every time
4. Logs are append-only - Never modify existing log entries
5. Rollback must be supported - Every action must be reversible
6. QA gates must pass - No deployment without green gates
7. No silent failures - Every error must be logged and visible
8. Version must be kept current - Every session updates version
9. Roadmap must be synchronized - Roadmap reflects all actions
10. This skill is mandatory - Every orchestrated action invokes it

References

See the following files for detailed specifications:

• references/version-schema.md - JSON schemas for all log structures
• references/audit-trail-design.md - Audit trail architecture and patterns
• references/hallucination-detection.md - Detailed hallucination detection algorithms
• references/qa-gates.md - Complete QA gate specifications (30 gates)
• scripts/version-log.sh - Bash implementation of logging system

Last Updated: 2026-03-22 Version: 1.0.0 Status: PRODUCTION