ponomar-pwa/.ai-specs/WORKING_POLICIES.md

Working Policies for AI Agents

Data Modification Rules

Never Overwrite Existing Content

• CRITICAL: Never overwrite existing life.text fields in lives entries
• Enrichment pipeline only fills empty entries
• If a target already has content, classify as already-filled and skip
• Bulgakov is secondary source: fills gaps only, never overrides Minei content

File Modification Permissions

• Allowed: Adding new life.text to empty entries
• Allowed: Adding manual fixes to enrich-lives.ts MANUAL_FIXES
• Allowed: Correcting menaion-bundle.json for CId date corrections
• Forbidden: Modifying existing life.text content
• Forbidden: Deleting or renaming CIds without proper validation
• Forbidden: Changing JSON structure without updating related code

Liturgical Content Policies

Never Translate Service or Bible Texts

• All liturgical and scriptural texts must be sourced through the data pipeline (original-language conversions, Chetyi-Minei, Bulgakov, EPUB/PDF imports, etc.)
• Never machine-translate, paraphrase or invent text — not even "just one line"
• Missing text stays empty (the app falls back serviceLang → cu → shared) until its source is converted

Church Slavonic Texts Are Presented Verbatim

• Never "normalise", latinise, transliterate or strip diacritics/accents/titla from cu texts
• Render the text exactly as stored in the source data; display-layer transformations are forbidden
• Orthography fixes belong in the conversion pipeline and must preserve the source

Service Assembly Follows the Typicon

• Service-building logic (templates, ordering, conditional rules, canons) must reproduce the Typicon
• Whenever service building logic is changed, check the expected structure against the Typicon (and the pinned service data) before and after the change

Validation Requirements

Pre-Commit Checklist

All changes must pass all three checks:

# 1. Type safety
npx tsc --noEmit
# Expected: No TypeScript errors

# 2. Build verification
npm run build
# Expected: Successful build with reasonable bundle sizes

# 3. Data validation
npx tsx scripts/validate-data.ts
# Expected: "All files valid!" or specific error count

When to Stop

• Stop immediately if any validation fails
• Fix errors before proceeding
• Address TypeScript compilation issues
• Check build output for unexpected size changes

Commit Message Standards

Format Conventions

Enrichment commits:

enrich [N] more ru lives: [brief description]

Bundle fix commits:

fix bundle: move [saint] from [date1] to [date2]

Script updates:

update [script name]: [brief description]

General guidance:

• Be specific about what changed
• Reference specific CIds or dates when applicable
• Keep messages concise but descriptive

File Change Guidelines

Static Data Files

• Tracked: static/data/ directory (all JSON files tracked)
• Not tracked: scripts/output/minei.json, scripts/output/bulgakov.json
• Validate: Always run typecheck and build after data changes

Script Files

• Maintain existing code patterns
• Use existing helper functions when available
• Update documentation in relevant markdown files

Output Files

• Generated files (dist/, scripts/output/) should not be committed
• Only commit source code and data files

Code Quality Standards

TypeScript Requirements

• Maintain strict typing
• Follow existing code conventions
• Add type annotations where appropriate
• Use proper error handling

Data Structure Integrity

• Maintain CId naming conventions
• Preserve JSON structure consistency
• Ensure required fields are present (name.nominative in lives entries)

Error Handling Protocols

When Validation Fails

1. Review error messages carefully
2. Identify root cause (JSON syntax, missing fields, type issues)
3. Fix the underlying problem
4. Re-run validation until it passes
5. Then proceed to type checking

When TypeScript Fails

1. Check for type mismatches in modified code
2. Verify imports and exports
3. Ensure all dependencies are properly declared
4. Fix type errors
5. Re-run tsc --noEmit

When Build Fails

1. Check console output for specific errors
2. Verify data file integrity
3. Check for import/export issues
4. Resolve build errors before proceeding

Documentation Requirements

When Modifying Data Schemas

• Update relevant documentation files (DATA_EN.md, DATA_RUS.md)
• Note any breaking changes or invariants
• Update project README if structural changes

When Adding New Scripts

• Document the script's purpose and usage
• Add NPM script entry if needed
• Update project documentation as appropriate

Common Operational Pitfalls

Data Modification Risks

• ⚠️ Don't accidentally overwrite existing life.text — Always check before writing
• ⚠️ Don't skip validation — Always validate before committing
• ⚠️ Don't ignore build errors — Build failures indicate real problems
• ⚠️ Don't commit generated files — Avoid committing dist/ or output files

Code Change Risks

• ⚠️ Don't break existing patterns — Follow established code conventions
• ⚠️ Don't duplicate logic — Use existing helper functions
• ⚠️ Don't ignore type safety — Maintain TypeScript strict typing
• ⚠️ Don't make undocumented changes — Update relevant documentation

Commit Risks

• ⚠️ Don't commit without validation — Ensure all checks pass
• ⚠️ Don't write vague commit messages — Be specific about what changed
• ⚠️ Don't assume static/data/ is excluded — It's tracked, commit your changes

Workflow for New Enrichment Work

Before Starting

1. Review existing MANUAL_FIXES in enrich-lives.ts
2. Understand the current coverage status
3. Identify which source (Minei or Bulgakov) and dates you're targeting

During Work

1. Use dry runs first: npx tsx scripts/enrich-lives.ts
2. Review the match report carefully
3. Add MANUAL_FIXES only for problematic matches
4. Re-run dry run until satisfied with results
5. Only use --write when confident

After Completion

1. Verify file sizes are reasonable
2. Check that collision appends are correct
3. Run full validation suite
4. Commit with descriptive message

Quality Assurance Standards

Coverage Tracking

• Monitor coverage statistics: 1203/3046 lives with text
• Track unmatched counts: 27 Minei + 121 Bulgakov (floor)
• Report changes in coverage when adding MANUAL_FIXES

Content Verification

• For collision targets, verify chapter counts
• Check that first chapter being unheaded is expected behavior
• Verify that life.text contains expected content for known CIds

Consistency Checks

• Ensure similar fixes follow the same pattern
• Maintain consistency with existing MANUAL_FIXES format
• Keep naming conventions consistent across all entries

Quick Reference for Common Operations

Adding a MANUAL_FIX

const MANUAL_FIXES: Record<string, string> = {
  'MM-DD|distinctive-substring': 'CId',
};

• Key format: ${date}|${substring} → CId
• Substring must be unique within that date
• CId must be empty for the fix to have effect

Running Enrichment

# Minei dry run
npx tsx scripts/enrich-lives.ts

# Minei write
npx tsx scripts/enrich-lives.ts --write

# Bulgakov dry run
npx tsx scripts/enrich-lives.ts --bulgakov

# Bulgakov write
npx tsx scripts/enrich-lives.ts --bulgakov --write

# Single month
npx tsx scripts/enrich-lives.ts --month 01
npx tsx scripts/enrich-lives.ts --write --month 01

Validating Data

# Main validator
npx tsx scripts/validate-data.ts

# Period-specific validators
npx tsx scripts/validate-menaion.ts
npx tsx scripts/validate-triodion.ts

Quick Coverage Check

python3 -c "
import json,glob,os
total=has=0
for fp in sorted(glob.glob('static/data/ru/lives/*.json') + glob.glob('static/data/ru/lives/misc/*.json')):
    data=json.load(open(fp))
    for cid,entry in data.items():
        total+=1
        if isinstance(entry.get('life'),dict) and entry.get('life',{}).get('text'):
            has+=1
print(f'Coverage: {has}/{total} ({has*100//total}%) lives with text')
"