Versify

Versify (Stage 6b Structural Validation)

Validate and import the generated translation from Stage 6a.

This skill is the Stage 6b owner — the second half of Stage 6.

Its input is the generated translation from translation-synthesis (Stage 6a). Its job is:

• Verify structural 1:1 alignment with Greek (should be true by construction)
• Validate coverage and quality metrics
• Import/prepare the verse-aligned edition for downstream use
• Report any issues that need resolution before proceeding

Important Policy

This skill has two modes:

1. Fast path (/versify try-witness): Attempt to versify a versification-candidate witness directly. This is reference-based matching only — no DP alignment, no range alignment, no structural modification. The witness either maps 1:1 to Greek segments as-is, or it fails.

2. Standard path (/versify run): Validate and import the generated translation from Stage 6a. This is the original behavior.

This skill does NOT:

• Generate translations (that's Stage 6a — translation-synthesis)
• Use DP alignment, range alignment, or force-fitting modes
• Try to "fix" structural mismatches in witness translations
• Attempt versification on witnesses NOT classified as versification-candidate

The fast path is strictly opt-in via Stage 5 classification. It succeeds or fails cleanly — there is no partial-match fallback.

Quick Status

Verse-aligned editions: !nix-shell -p sqlite --run "sqlite3 data/editions.db \"SELECT code FROM editions WHERE code LIKE '%-verse-%' OR urn LIKE '%generated%'\"" 2>/dev/null Generated edition segments: !nix-shell -p sqlite --run "sqlite3 data/editions.db \"SELECT e.code, COUNT(s.id) FROM editions e JOIN segments s ON s.edition_id=e.id WHERE e.urn LIKE '%generated%' GROUP BY e.code\"" 2>/dev/null

Commands

• /versify try-witness [work] — Attempt to versify a versification-candidate witness directly (fast path)
• /versify run [work] — Validate and import the generated translation from Stage 6a
• /versify validate [work] — Re-validate an already-imported generated translation
• /versify status [work] — Summarize validation state, coverage, and blockers

Target: $ARGUMENTS

---

Owned Responsibilities

Owns

• Stage 6b structural validation
• 1:1 alignment verification (generated English ↔ Greek)
• Coverage metrics and reporting
• DB import of generated translations
• Per-book isolation safeguards

Does not own

• Translation generation (Stage 6a — translation-synthesis)
• Witness gathering and ranking (Stage 5 — translation-witness)
• Interlinear generation (Stage 8)
• Reader reliability verification (Stage 9)
• Final ship promotion (Stage 10)

---

Input Requirements

Before running /versify run, these must be complete:

1. Stage 6a complete: Generated translation chapter files exist under $LYCEUM_TEXTS_DIR/<slug>/versification/
2. Chapter files have segments: Each chapter file contains segments array with reference and translation fields
3. Adversarial review done: Chapter files include reviews array (even if all verdicts are "pass")

If Stage 6a is incomplete, this skill should report the gap and direct to /translation-synthesis run <work>.

---

Workflows

/versify try-witness

Attempt to versify a versification-candidate witness directly, without generating a new translation.

This is the Stage 6 fast path. The orchestrator calls this BEFORE /translation-synthesis run. If it succeeds, Stage 6a generation is skipped entirely.

Prerequisites

• Stage 5 complete: witness catalog exists with role classifications
• Greek edition segments exist in the database
• At least one witness is classified as versification-candidate

Execution steps

1. Load witness catalog

   cat $LYCEUM_TEXTS_DIR/<slug>/sources/english_candidates.json
   

   Find all witnesses with "versification-candidate" in their roles array.

2. For each candidate (in catalog order):

   a. Load witness text from witnesses/<file>

   b. Parse references using the witness format field (same import logic as Path A in translation-witness)

   c. Match references to Greek segments:

   • Direct match: witness reference equals Greek reference exactly
   • Parent-prefix match: witness reference is a parent of a Greek sub-segment (e.g., witness 1.1 matches Greek 1.1.1, 1.1.2, 1.1.3)
   • For parent-prefix matches, the witness text is duplicated across sub-segments (acceptable for display, downstream interlinear generates fresh glosses regardless)

   d. Compute metrics:

   • greek_segment_count: total Greek segments
   • witness_segment_count: total parsed witness segments
   • matched_segments: Greek segments with a witness match
   • coverage: matched_segments / greek_segment_count
   • empty_segments: matched segments where witness text is empty/whitespace

   e. Apply pass criteria:

   • Coverage MUST be 100% (every Greek segment has a witness match)
   • No empty segments
   • Segment count ratio within 10% (abs(witness - greek) / greek <= 0.10)

3. On success (first candidate that passes):

   • Import the witness as the versified edition in the DB
   • Edition URN must use a distinct versified marker — pattern: {base}-versified-eng1 (e.g., perry-versified-eng1). Never reuse the witness URN.
   • Set generated_edition_urn in manifest to the versified URN (keep english_edition_urn as the witness URN)
   • Set edition_urn in english_versified.json to match generated_edition_urn
   • Edition label indicates the source (e.g., "ASV (versified witness)")
   • Write versification report to qa/alignment-report.md
   • Return success with metrics

4. On failure (no candidate passes):

   • Write report documenting each candidate and why it failed
   • Return failure — the orchestrator will proceed to Stage 6a generation

Output

Success report

# Stage 6 Fast Path: Witness Versification

## Result: SUCCESS

## Witness used
- ID: asv-1901
- Title: American Standard Version (1901)
- Coverage: 100% (7957/7957 segments)
- Empty segments: 0
- Import: versified-witness edition created

## Metrics
- Greek segments: 7957
- Witness segments: 7956 (1 parent-prefix expansion)
- Matched: 7957/7957 (100%)

## Next steps
- Stage 6a (translation-synthesis) SKIPPED
- Proceed to Stage 7 (transliteration) or Stage 8 (interlinear)

Failure report

# Stage 6 Fast Path: Witness Versification

## Result: FAILED — falling back to Stage 6a generation

## Candidates attempted
### asv-1901
- Coverage: 94.2% (7496/7957 segments)
- Reason: coverage below 100% — 461 Greek segments unmatched
- Missing references: 1.1.2, 1.1.3, ... (reference mismatch in sub-segments)

## Next steps
- Proceed to /translation-synthesis run [work]

---

/versify run

Validate and import the generated translation.

Validation checks

1. Structural alignment

   • Every Greek segment has a corresponding generated English segment
   • No extra segments in the generated translation
   • References match exactly (same format, same numbering)

2. Per-book isolation

   • Segments from different chapters are not mixed
   • Import operates chapter-by-chapter

3. Coverage metrics

   • Total segment count matches Greek
   • No empty translations
   • No duplicate references

4. Review status

   • All chapters have been adversarially reviewed
   • High-severity issues documented

Import steps

# Import generated translation to DB
python3 scripts/generate_translation.py --text <text_key> --import-only

Or via direct SQL for custom workflows:

-- Check if generated edition exists
SELECT id, urn FROM editions WHERE urn LIKE '%generated%';

-- Verify segment count matches Greek
SELECT 
  (SELECT COUNT(*) FROM segments WHERE edition_id = <greek_id>) as greek_count,
  (SELECT COUNT(*) FROM segments WHERE edition_id = <generated_id>) as generated_count;

Output

After successful validation and import:

• Generated edition exists in DB with segments
• Edition URN includes "generated" marker
• Edition label indicates it's a generated translation
• qa/alignment-report.md updated with validation results

---

/versify validate

Re-validate an already-imported generated translation without re-importing.

When to use

• After DB changes that might have affected segments
• When verifying integrity before downstream work
• As part of replay/rehab workflows

Checks

• DB segment count matches expected
• No gaps or duplicates in reference sequence
• Generated edition metadata is correct

---

/versify status

Report current state.

Report includes

• Generated translation existence (chapter files)
• Import status (DB edition exists/missing)
• Coverage: segments imported vs expected
• Blockers: unresolved issues preventing downstream work
• Next recommended action

---

Legacy Scripts (Maintenance Only)

These scripts exist for maintaining older texts that used legacy alignment modes. They are not used for new work.

Script	Text	Mode	Notes
scripts/versify_meditations.py	Meditations	DP	Legacy: explicit Book 1 map + DP
scripts/versify_homer.py	Iliad/Odyssey	range	Legacy: range fallback

Important: Do not extend these scripts or use their patterns for new texts. All new texts go through translation-synthesis (Stage 6a) then versify (Stage 6b).

Deleted legacy scripts: versify_john.py and versify_aesop.py were removed; existing data for these texts uses the fast path (Stage 6 witness versification).

---

Validation Report Format

The validation report should include:

# Stage 6b Validation Report

## Work
- Slug: <slug>
- Greek edition: <edition_id>
- Generated edition URN: <urn>

## Coverage
- Greek segments: N
- Generated segments: N
- Match: ✓ / ✗

## Structural checks
- [x] 1:1 reference alignment
- [x] No cross-chapter contamination  
- [x] No empty translations
- [x] No duplicate references

## Review summary
- Chapters reviewed: N
- Pass verdicts: N
- Fail verdicts: N
- Total issues logged: N

## Import status
- Edition imported: ✓ / ✗
- Edition ID: <id>

## Blockers
- (none) or (list)

## Next steps
- Ready for Stage 8 (interlinear) or Stage 9 (reader-reliability)

---

Important Rules

Generated translation only

This skill validates and imports only the generated translation from Stage 6a. It does not:

• Create alignments from existing PD translations
• Use DP/range/direct-mapping algorithms
• Modify witness translations to fit Greek structure

Witness versification is reference-matching only

PD witness translations (gathered in Stage 5) remain structurally unmodified:

• They are reference material for adversarial review
• They may be displayed in the reader as alternative translations
• They are never structurally modified or forced into 1:1 alignment via DP/range algorithms
• A versification-candidate witness may be versified via /versify try-witness, but ONLY through direct reference matching — the witness either already maps 1:1, or the attempt fails

Versified editions MUST use a distinct URN

When the witness fast-path produces a versified edition, it must use a distinct URN that differs from the original witness URN. The pattern is {base}-versified-eng1 (e.g., perry-versified-eng1 not perry-eng1). This is critical because:

• The original witness edition must remain importable with its own segment count and structure
• Reusing the witness URN would cause the import to overwrite the witness with the versified edition, losing the original translation
• The generated_edition_urn field in manifest.json must reflect the versified URN, while english_edition_urn stays as the witness URN
• The edition_urn field in english_versified.json must match generated_edition_urn

Never set generated_edition_urn equal to english_edition_urn when a versified edition is produced.

⚠️ DO NOT manually set edition URNs in manifest.json

CRITICAL: Do NOT manually set english_edition_urn or generated_edition_urn in manifest.json.

The import script (Stage 10) auto-generates these URNs with the "versified" convention that the reader requires:

• The reader checks for "versified", "verse", or "gen-eng" in the English edition URN to enable row view
• Manually overriding these fields breaks row view detection
• Users will see broken/incomplete reader layout

What happens at Stage 10:

• Import script generates URNs like <work_urn>.workspace-versified-eng1
• The "versified" marker activates row view in the reader
• Both URNs are written automatically based on the versification output

If you manually set URNs:

• Row view will NOT activate
• The validation in scripts/import_workspace.go will warn
• The text will fail reader reliability checks (Stage 9)

Leave english_edition_urn and generated_edition_urn blank in manifest.json.

Row view requires versified translation

Only versified (generated) translations may render in row view. This is because:

• Row view requires 1:1 structural correspondence with Greek
• Only the generated translation has this property by construction
• Witness translations have arbitrary structure and cannot be row-aligned

If a text lacks a versified generated translation, row view is unavailable for that text.

Legacy grandfathering

Pre-2026-03-16 texts with verse-aligned witness editions are grandfathered:

• Meditations (Long, Haines)
• John (Perseus, ASV)
• Hymn 7 (Lucas)
• Alexander (Perrin)

These existing verse-aligned witnesses remain functional. New texts may get a versified witness edition ONLY through the fast path (/versify try-witness) when Stage 5 classifies a witness as versification-candidate and automated versification succeeds. All other new texts must go through Stage 6a generation.

Coverage is 100% or blocked

Because the generated translation is structure-preserving by construction:

• Coverage should be 100%
• Any coverage gap indicates a Stage 6a problem (missing chapters, generation failure)
• Partial coverage is a blocker, not an acceptable state

Biblical versification awareness

When processing NT or OT texts:

• Ghost verses: Different editions may include or exclude disputed verses (Matt 17:21, Mark 7:16, John 5:4, Acts 8:37, etc.). The pipeline follows the base Greek edition's numbering. If a verse is absent from the Greek edition, no segment is created for it.
• Sub-verse notation: References like 3.16a and 3.16b are valid if the base edition uses them.
• Cross-tradition numbering: LXX and MT psalm numbering differ. The pipeline uses whichever numbering the source Greek edition provides. Document the tradition in the workspace manifest.
• Verse divisions splitting clauses: This is normal and expected — Estienne's 1551 verse divisions were pragmatic, not linguistic. The pipeline preserves these boundaries because they are the universal reference standard, even when linguistically awkward.

---

Verification Contract

This skill follows the Stage 6b contract.

Verify

• Generated translation exists (chapter files present)
• 1:1 structural alignment verified
• Coverage is 100%
• No cross-book leakage
• DB import successful

Minimum evidence

• qa/alignment-report.md with validation results
• Generated edition in DB with correct segment count
• No blockers documented

Pass criteria

• Every Greek segment has a generated English segment
• Import completed without errors
• Edition URN and label correctly indicate generated status
• Ready for downstream stages

Failure examples

• Generated translation missing for some chapters
• Reference mismatches between Greek and generated
• Import failed or created incorrect segment count
• Attempting to align a PD witness instead of generated translation

Required next steps

After successful Stage 6b:

• Stage 8 (interlinear/morphology) can proceed
• Stage 9 (reader-reliability) for product QA
• Stage 10 (ship gate) when ready for final review

---

Verification

After completing this stage, run the automated verification script:

bash scripts/verify_stage_6b.sh "${SLUG}"

Exit codes: 0=PASS (advance), 1=FAIL (block), 2=WARN (advance with notes). The orchestrator runs this automatically; when executing manually, check the output for [FAIL] or [WARN] lines.

---

Key Files

File	Purpose
scripts/generate_translation.py	Stage 6a generation + optional import
$LYCEUM_TEXTS_DIR/<slug>/versification/	Generated translation chapter files
qa/alignment-report.md	Validation report
.pi/skills/translation-synthesis/SKILL.md	Stage 6a (generation)
.pi/skills/translation-witness/SKILL.md	Stage 5 (witness collection)
docs/text-pipeline-master-plan-2026-03-13.md	Pipeline architecture

Legacy scripts (maintenance only)

File	Purpose
scripts/versify_meditations.py	Legacy Meditations DP alignment
scripts/versify_homer.py	Legacy Homer range fallback
(deleted)	Legacy batch helper