Commit Skill

The commit skill finalizes approved encoding by organizing files, updating indices, creating git commits, archiving session artifacts, and preparing for the next encoding cycle.

Overview

Attribute	Value
Skill Name	commit
Phase	5 of 5 (Terminal)
Checkpoint	None - all approvals already obtained
Prerequisites	All checkpoints (1-4) approved
Outputs	Git commit, updated manifest, archived session
Trigger Phrases	"commit encoding", "finalize encoding", "save encoding", "complete encoding"

Prerequisites

Before this skill can execute:

1. Review checkpoint MUST be approved
2. Human has verified both checklists
3. Session state shows review.status: approved
4. All validation tests passing

Phase A: Pre-Commit Verification

Step 1: Verify All Checkpoints Cleared

The skill verifies all required checkpoints are approved:

session = load_session_state()

required_checkpoints = ['corpus-prep', 'hll-encode', 'validate', 'review']
for checkpoint in required_checkpoints:
    status = session['checkpoints'][checkpoint]['status']
    assert status == 'approved', f"Checkpoint {checkpoint} not approved: {status}"

Checkpoint Status Requirements:

Checkpoint	Required Status
corpus-prep	approved
hll-encode	approved
validate	approved
review	approved

Step 2: Final Validation Run

One final validation ensures nothing changed since approval:

# Run full test suite
pytest tests/ontology/ -v --tb=short

# Verify encoding compiles
python -c "from mistaber.engine import HsrsEngine; e = HsrsEngine(Path('mistaber/ontology'))"

Step 3: Metadata Finalization

The skill prepares commit metadata:

encoding_metadata:
  reference: "YD:87:3"
  encoded_at: "2026-01-25T16:30:00Z"
  reviewer: "human_reviewer_name"
  version: "1.0.0"
  checkpoints:
    corpus_prep: "2026-01-25T10:30:00Z"
    hll_encode: "2026-01-25T12:00:00Z"
    validate: "2026-01-25T14:00:00Z"
    review: "2026-01-25T16:00:00Z"
  metrics:
    rules_count: 8
    worlds: [base, mechaber, rema]
    machloket_count: 1
    test_count: 25

Phase B: File Organization

Step 1: Ontology File Placement

The skill ensures files are in correct locations following the actual codebase pattern:

File Organization:

mistaber/ontology/
├── corpus/
│   └── yd_{siman}/
│       ├── manifest.yaml        # Siman manifest (create/update)
│       └── base.lp              # Shared definitions (updated)
├── worlds/
│   ├── mechaber.lp              # Mechaber-specific rules (updated)
│   ├── rema.lp                  # Rema-specific rules (updated)
│   └── ...
└── tests/
    └── yd_{siman}/
        ├── seif_{seif}_test.yaml     # Test scenarios
        └── seif_{seif}_metadata.yaml # Encoding metadata

Step 2: Update Siman Manifest

The skill creates or updates yd_{siman}/manifest.yaml:

# mistaber/ontology/corpus/yd_87/manifest.yaml
siman: 87
title: "Basar Bechalav (Meat and Milk)"
source: "Shulchan Aruch Yoreh Deah Siman 87"

seifim:
  - number: 1
    title: "Beheima + Chalav: D'oraita"
    encoded_at: "2026-01-20T10:00:00Z"
    rules_count: 6
    status: complete

  - number: 3
    title: "Dag Bechalav: Machloket"
    encoded_at: "2026-01-25T16:30:00Z"  # NEW ENTRY
    rules_count: 8
    status: complete

coverage:
  total_seifim: 11
  encoded_seifim: 2
  percentage: 18.2

Step 3: Create Metadata File

The skill creates seif_{seif}_metadata.yaml:

# Encoding metadata for YD 87:3
reference: "YD:87:3"
title: "Dag Bechalav (Fish and Dairy)"

encoding:
  date: "2026-01-25T16:30:00Z"
  reviewer: "human_reviewer_name"
  corpus_artifact: "corpus-sources-YD-87-3.yaml"

metrics:
  rules_count: 8
  base_rules: 2
  world_specific_rules: 6
  machloket_markers: 1
  worlds_covered:
    - base
    - mechaber
    - rema

sources:
  primary: "SA YD 87:3"
  commentaries:
    - shach
    - taz
  chain_depth: 4
  chain_terminus: "Beit Yosef"

validation:
  tests_total: 25
  tests_passed: 25
  regression_passed: true

Step 4: Archive Session Artifacts

The skill moves working artifacts to archive:

docs/encoding-sessions/
└── yd_87_3_2026-01-25/
    ├── corpus-report.md
    ├── corpus-sources.yaml
    ├── corpus-chain.mermaid
    ├── corpus-questions.yaml
    ├── encoding-report.md
    ├── encoding-mapping.yaml
    ├── validation-report.md
    ├── validation-results.yaml
    ├── test-scenarios.yaml
    ├── review-package.md
    ├── source-chain-log.yaml
    └── session-state.yaml

Step 5: Update Index Files

If project has index files, they are updated:

# Update corpus index if exists
index_path = Path("mistaber/ontology/corpus/index.yaml")
if index_path.exists():
    index = yaml.safe_load(index_path.read_text())
    index['simanim'][f'yd_87']['seifim'].append({
        'number': 3,
        'file': 'base.lp',  # Shared definitions
        'encoded': "2026-01-25T16:30:00Z"
    })
    index_path.write_text(yaml.dump(index))

Phase C: Git Operations

Step 1: Stage Files

The skill stages only relevant files:

# Stage ontology files
git add mistaber/ontology/corpus/yd_87/base.lp
git add mistaber/ontology/corpus/yd_87/manifest.yaml
git add mistaber/ontology/worlds/mechaber.lp
git add mistaber/ontology/worlds/rema.lp

# Stage test files
git add mistaber/ontology/tests/yd_87/seif_3_test.yaml
git add mistaber/ontology/tests/yd_87/seif_3_metadata.yaml

# Stage archived session
git add docs/encoding-sessions/yd_87_3_2026-01-25/

Step 2: Generate Commit Message

The skill generates a conventional commit message:

feat(ontology): encode YD 87:3 - Dag Bechalav machloket

Encode Shulchan Aruch Yoreh Deah 87:3 (Fish and Dairy dispute).

Encoding Summary:
- 8 rules encoded (2 base, 6 world-specific)
- Worlds: base, mechaber, rema
- Machloket: Mechaber (sakana) vs Rema (mutar)
- Tests: 25 scenarios (all passing)

Key Rules:
- r_bb_dag_no_bb: Fish has no basar bechalav issur (base)
- r_bb_dag_sakana: Fish + dairy = sakana (mechaber)
- r_rema_dag_chalav_mutar: Fish + dairy permitted (rema)

Sources:
- Primary: SA YD 87:3
- Commentaries: Shach, Taz, Beit Yosef

Reviewed-by: human_reviewer_name
Corpus-artifact: corpus-sources-YD-87-3.yaml
Session-archive: docs/encoding-sessions/yd_87_3_2026-01-25/

Step 3: Create Commit

git commit -m "$(cat <<'EOF'
feat(ontology): encode YD 87:3 - Dag Bechalav machloket

Encode Shulchan Aruch Yoreh Deah 87:3 (Fish and Dairy dispute).

Encoding Summary:
- 8 rules encoded (2 base, 6 world-specific)
- Worlds: base, mechaber, rema
- Machloket: Mechaber (sakana) vs Rema (mutar)
- Tests: 25 scenarios (all passing)

Sources:
- Primary: SA YD 87:3
- Commentaries: Shach, Taz, Beit Yosef

Reviewed-by: human_reviewer_name
Corpus-artifact: corpus-sources-YD-87-3.yaml
EOF
)"

Step 4: Verify Commit

# Show commit
git show --stat HEAD

# Verify committed files
git diff-tree --no-commit-id --name-only -r HEAD

Phase D: Post-Commit

Step 1: Update Progress Tracking

The skill updates encoding progress:

# docs/encoding-progress.yaml
yoreh_deah:
  siman_87:
    title: "Basar Bechalav"
    total_seifim: 11
    encoded:
      - seif: 1
        date: "2026-01-20"
        commit: "abc123"
      - seif: 3
        date: "2026-01-25"
        commit: "def456"  # NEW
    remaining: [2, 4, 5, 6, 7, 8, 9, 10, 11]
    coverage: 18.2%

Step 2: Clean Up Session State

The skill archives and resets session:

# Archive session state
cp .mistaber-session.yaml docs/encoding-sessions/yd_87_3_2026-01-25/

# Reset for next encoding
rm .mistaber-session.yaml
rm -rf .mistaber-artifacts/

Step 3: Suggest Next Steps

The skill analyzes and suggests next encoding:

## Next Steps

### Suggested Next Seif

Based on dependency analysis and encoding order:

**Recommended:** YD 87:4 (Treifa in Basar Bechalav)
- Dependencies: YD 87:1 (encoded), YD 87:3 (encoded)
- Complexity: Low (4/10)
- Estimated effort: 1-2 hours

**Alternative:** YD 87:5 (Bitul in Basar Bechalav)
- Dependencies: YD 87:1 (encoded)
- Complexity: Medium (6/10)
- Estimated effort: 2-3 hours

### Siman 87 Progress

[████░░░░░░░░░░░░░░░░] 18% (2/11 seifim)

Seif 1: Beheima + Chalav (d'oraita) Seif 2: Species clarification Seif 3: Dag Bechalav (machloket) Seif 4: Treifa exception Seif 5: Bitul rules ...

### To Start Next Encoding

User: "Prepare corpus for YD 87:4"

Step 4: Generate Summary Report

Final summary for human:

# Encoding Complete: YD 87:3

## Commit Details
- **Commit:** def456789...
- **Date:** 2026-01-25T16:30:00Z
- **Branch:** main

## Files Committed
- `mistaber/ontology/corpus/yd_87/base.lp` (shared definitions)
- `mistaber/ontology/corpus/yd_87/manifest.yaml`
- `mistaber/ontology/worlds/mechaber.lp` (world-specific)
- `mistaber/ontology/worlds/rema.lp` (world-specific)
- `mistaber/ontology/tests/yd_87/seif_3_test.yaml`
- `mistaber/ontology/tests/yd_87/seif_3_metadata.yaml`
- `docs/encoding-sessions/yd_87_3_2026-01-25/` (archive)

## Metrics
- Rules encoded: 8
- Tests created: 25
- Coverage increase: 9.1% → 18.2%

## Session Archived
All artifacts archived to:
`docs/encoding-sessions/yd_87_3_2026-01-25/`

---

**Ready for next encoding cycle.**

Completion Criteria

The commit skill completes when:

• [ ] All four prior checkpoints approved
• [ ] Final validation passes
• [ ] Files organized correctly
• [ ] Manifest updated
• [ ] Git commit created
• [ ] Session archived
• [ ] Progress updated
• [ ] Next steps suggested

Session State (Final)

After commit:

current_phase: complete
target_seif: "YD:87:3"
completed_at: "2026-01-25T16:30:00Z"
commit_hash: "def456789..."
checkpoints:
  corpus-prep:
    status: approved
  hll-encode:
    status: approved
  validate:
    status: approved
  review:
    status: approved
  commit:
    status: complete
    commit_hash: "def456789..."
    files_committed: 7

Hook Interaction

Git Commit Guard

The git-commit-guard hook verifies all checkpoints before allowing commit:

# Hook checks:
# 1. Active session exists
# 2. All checkpoints approved
# 3. Ontology files are staged

if review_status != "approved":
    # BLOCK with message
    return {"continue": False, "message": "Review not approved"}

# If all checks pass:
return {"continue": True, "message": "Git commit guard: Review approved"}

Post-Commit Cleanup

The skill handles cleanup after successful commit:

1. Archives .mistaber-session.yaml
2. Removes .mistaber-artifacts/
3. Resets state for next session

Common Issues

Commit Blocked by Guard

Symptom: Git commit blocked by git-commit-guard hook.

Causes: - Review checkpoint not approved - Session state file missing - Wrong files staged

Solutions: 1. Verify all checkpoints approved 2. Check .mistaber-session.yaml exists 3. Ensure ontology files are staged

Merge Conflicts

Symptom: Git reports merge conflicts.

Solutions: 1. Pull latest changes first 2. Resolve conflicts in ontology files carefully 3. Re-run validation after conflict resolution

Archive Creation Fails

Symptom: Cannot create archive directory.

Solutions: 1. Check disk space 2. Verify write permissions 3. Create parent directories if needed

Related Documentation

• Review Skill - Previous phase
• Workflow Guide - Complete pipeline overview
• Troubleshooting - Error resolution