Commit and Finalization

The commit phase finalizes the approved encoding by organizing files, creating a git commit, archiving the session, and preparing for the next encoding cycle. The commit skill handles all finalization tasks after all four checkpoints have been cleared.

Purpose

The commit skill accomplishes:

1. Pre-Commit Verification: Ensure all checkpoints are approved
2. File Organization: Place files in correct locations
3. Git Operations: Stage, commit with proper message
4. Session Archival: Preserve artifacts for future reference
5. Next Steps: Suggest what to encode next

Prerequisites

Before invoking this skill:

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

Invoking the Skill

After review approval:

User: "Commit the encoding"

The skill automatically:

1. Verifies all checkpoints are cleared
2. Runs final validation
3. Organizes files
4. Creates git commit
5. Archives session
6. Suggests next steps

Phase A: Pre-Commit Verification

Step 1: Verify All Checkpoints Cleared

The skill checks session state:

session = load_session_state()

required_checkpoints = ['corpus-prep', 'hll-encode', 'validate', 'review']
for checkpoint in required_checkpoints:
    status = session['checkpoints'][checkpoint]['status']
    if status != 'approved':
        raise WorkflowError(
            f"Checkpoint {checkpoint} not approved: {status}"
        )

Step 2: Final Validation Run

Run one final validation to ensure nothing changed since review:

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

# Verify encoding still compiles
python -c "
from mistaber.engine import HsrsEngine
from pathlib import Path
e = HsrsEngine(Path('mistaber/ontology'))
print('Engine loaded successfully')
"

If validation fails at this stage, the commit is blocked and the user is notified.

Step 3: Metadata Finalization

Prepare commit metadata:

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

Phase B: File Organization

Step 1: Ontology File Placement

The skill ensures all files are in correct locations:

File Structure (CRITICAL - follows actual codebase pattern):

mistaber/ontology/
├── corpus/
│   └── yd_87/
│       ├── manifest.yaml        # Siman manifest (create/update)
│       └── base.lp              # Shared definitions (new/updated)
├── worlds/
│   ├── mechaber.lp              # Mechaber-specific rules (updated)
│   ├── rema.lp                  # Rema-specific rules (updated)
│   └── ...
└── tests/
    └── yd_87/
        ├── seif_3_test.yaml     # Test scenarios for this seif
        └── seif_3_metadata.yaml # Encoding metadata

Step 2: Update Siman Manifest

Create or update the siman manifest:

# 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

Create the seif metadata file:

# mistaber/ontology/tests/yd_87/seif_3_metadata.yaml
reference: "YD:87:3"
title: "Fish and Dairy (Dag Bechalav)"

encoding:
  date: "2026-01-25T16:30:00Z"
  reviewer: "{human_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: 3
  chain_terminus: "Historical medical sources"

validation:
  tests_total: 19
  tests_passed: 19
  regression_passed: true

machloket:
  - topic: dag_chalav
    authorities: [mechaber, rema]
    practical_difference: "Fish with dairy dishes"

Step 4: Archive Session Artifacts

Move working artifacts to permanent 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
    ├── encoding-validation.yaml
    ├── validation-report.md
    ├── validation-results.yaml
    ├── test-scenarios.yaml
    ├── performance-metrics.yaml
    ├── review-package.md
    └── session-state.yaml

Step 5: Update Index Files

If the project has index files, update them:

# Update corpus index if it 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',
        'encoded': '2026-01-25T16:30:00Z'
    })
    index_path.write_text(yaml.dump(index))

Phase C: Git Operations

Step 1: Stage Files

Stage only the 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

Use conventional commits format:

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
- Worlds: base, mechaber, rema
- Machloket: Mechaber (sakana) vs Rema (mutar)
- Tests: 19 scenarios

Sources:
- Primary: SA YD 87:3
- Commentaries: Shach sk 5, Taz sk 3

Reviewed-by: {human_name}
Corpus-artifact: corpus-sources-YD-87-3.yaml

Step 3: Create Commit

Execute the 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
- Worlds: base, mechaber, rema
- Machloket: Mechaber (sakana) vs Rema (mutar)
- Tests: 19 scenarios

Sources:
- Primary: SA YD 87:3
- Commentaries: Shach sk 5, Taz sk 3

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

Step 4: Verify Commit

Confirm the commit succeeded:

# Show commit details
git show --stat HEAD

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

Expected output:

commit abc123def456 (HEAD -> main)
Author: Claude <claude@anthropic.com>
Date:   Sat Jan 25 16:30:00 2026 -0500

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

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

 docs/encoding-sessions/yd_87_3_2026-01-25/corpus-report.md     | 245 +++++++++
 docs/encoding-sessions/yd_87_3_2026-01-25/review-package.md    | 312 +++++++++++
 ...
 mistaber/ontology/corpus/yd_87/base.lp                         |  45 ++
 mistaber/ontology/corpus/yd_87/manifest.yaml                   |   8 +-
 mistaber/ontology/worlds/mechaber.lp                           |  28 +
 mistaber/ontology/worlds/rema.lp                               |  32 +
 ...
 8 files changed, 667 insertions(+), 3 deletions(-)

Phase D: Post-Commit

Step 1: Update Progress Tracking

Update the encoding progress tracker:

# 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

Archive and reset session:

# Archive session state (already done in archive step)

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

Step 3: Suggest Next Steps

Analyze what should be encoded next:

## Next Steps

### Suggested Next Seif

Based on dependency analysis and encoding order:

**Recommended:** YD 87:2 (Wild animals - Chaya)
- Dependencies: YD 87:1 (satisfied)
- Complexity: Low (3/10) - Simple extension of beheima rules
- Estimated effort: 1 hour

**Alternative:** YD 87:4 (Treifa in Basar Bechalav)
- Dependencies: YD 87:1 (satisfied)
- Complexity: Medium (5/10) - Exception handling
- Estimated effort: 2 hours

**Complex option:** YD 87:5 (Poultry with milk)
- Dependencies: YD 87:1 (satisfied)
- Complexity: Medium (6/10) - d'oraita vs d'rabanan distinction
- Estimated effort: 2-3 hours

### Siman 87 Progress

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

Seif 1: Beheima + Chalav (d'oraita) Seif 2: ◻️ Chaya (wild animals) Seif 3: Dag Bechalav (machloket) Seif 4: ◻️ Treifa exception Seif 5: ◻️ Poultry + dairy Seif 6: ◻️ Human milk Seif 7: ◻️ Kosher with non-kosher Seif 8: ◻️ Benefit prohibition Seif 9: ◻️ Cooking prohibition Seif 10: ◻️ Mixtures Seif 11: ◻️ Vessels

### To Start Next Encoding

```bash
# Invoke corpus-prep skill for next seif
User: "Prepare corpus for YD 87:2"

### Step 4: Generate Summary Report

Final summary for human:

```markdown
# Encoding Complete: YD 87:3

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

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

## Metrics
- Rules encoded: 8
- Tests created: 19
- Regression tests: 495 passed
- Coverage increase: 9.1% → 18.2%

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

## Session State
Session state cleared. Ready for next encoding cycle.

---

**Ready for next encoding cycle.**

Commit Message Conventions

The encoding workflow uses conventional commits format:

Format

<type>(scope): <subject>

<body>

<footer>

Types

Type	Usage
feat(ontology)	New encoding (most common)
fix(ontology)	Correction to existing encoding
refactor(ontology)	Restructure without changing behavior
docs(encoding)	Documentation only

Scope

Always use ontology for encoding commits.

Subject

Format: encode YD {siman}:{seif} - {topic}

Body

Include:

• Brief description
• Encoding summary (rules, worlds, machloket, tests)
• Sources (primary and commentaries)

Footer

Include:

• Reviewed-by: - Human reviewer name
• Corpus-artifact: - Source corpus file

Examples

Standard encoding:

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
- Worlds: base, mechaber, rema
- Machloket: Mechaber (sakana) vs Rema (mutar)
- Tests: 19 scenarios

Sources:
- Primary: SA YD 87:3
- Commentaries: Shach sk 5, Taz sk 3

Reviewed-by: Rabbi Expert
Corpus-artifact: corpus-sources-YD-87-3.yaml

Simple encoding (no machloket):

feat(ontology): encode YD 87:2 - Chaya with milk

Encode Shulchan Aruch Yoreh Deah 87:2 (Wild animals with milk).

Encoding Summary:
- 4 rules encoded
- Worlds: base
- No machloket
- Tests: 8 scenarios

Sources:
- Primary: SA YD 87:2

Reviewed-by: Rabbi Expert
Corpus-artifact: corpus-sources-YD-87-2.yaml

Correction:

fix(ontology): correct makor chain for r_bb_dag_sakana

The makor chain for r_bb_dag_sakana was missing the Beit Yosef reference
that documents the medical source basis.

Changes:
- Added makor(r_bb_dag_sakana, beit_yosef("yd:87"))
- Updated manifest

Reviewed-by: Rabbi Expert

Checkpoint Criteria

The commit skill completes the encoding cycle. All criteria from previous checkpoints must remain satisfied:

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

Session State (Final)

After successful commit:

current_phase: complete
target_seif: "YD:87:3"
completed_at: "2026-01-25T16:30:00Z"
commit_hash: "def456abc789"
checkpoints:
  corpus-prep:
    status: approved
    timestamp: "2026-01-25T10:30:00Z"
  hll-encode:
    status: approved
    timestamp: "2026-01-25T12:00:00Z"
  validate:
    status: approved
    timestamp: "2026-01-25T15:30:00Z"
  review:
    status: approved
    timestamp: "2026-01-25T16:00:00Z"
  commit:
    status: complete
    timestamp: "2026-01-25T16:30:00Z"
    commit_hash: "def456abc789"
    files_committed: 8

This session state is then archived and the working copy is deleted.

Troubleshooting

"Checkpoint not approved"

A required checkpoint was not cleared:

1. Check which checkpoint is pending
2. Return to that phase
3. Complete the checkpoint requirements
4. Return to commit

"Validation failed on final check"

Something changed since review approval:

1. Check what test is failing
2. Identify if files were modified
3. Return to validation phase
4. Re-approve review after fix

"Git commit failed"

Git operation encountered an error:

1. Check for merge conflicts
2. Verify staged files are correct
3. Check git repository state
4. Resolve and retry commit

"Cannot archive session"

Archive directory issues:

1. Check disk space
2. Verify write permissions
3. Check for existing archive with same name
4. Manually archive if needed

Best Practices

1. Verify before committing - Run final validation even if confident
2. Use descriptive commit messages - Future maintainers will thank you
3. Archive completely - Include all artifacts for reproducibility
4. Update progress tracking - Keep coverage metrics current
5. Suggest next steps - Maintain encoding momentum

Encoding Cycle Complete

Congratulations on completing an encoding cycle. The halachic content from the source seif is now:

1. Encoded in formal HLL/ASP rules
2. Validated with comprehensive tests
3. Reviewed by a human expert
4. Committed to the repository
5. Archived for future reference

The encoding is now part of the Mistaber ontology and can be:

• Queried via the engine API
• Used for halachic reasoning
• Extended in future encoding sessions
• Referenced by other encoded seifim

Related Documentation

• Encoding Overview - Pipeline overview and checkpoint model
• Getting Started - Initial setup and first encoding
• HLL Language Reference - Language syntax and semantics
• Predicate Registry - Available predicates
• Multi-World Semantics - World structure