New Text Ship

New Text Ship (Stage 10 Ship Gate)

Promote approved text-pipeline artifacts into shipped repo/DB state.

This skill is the Stage 10 owner for final review and promotion. It should answer:

• which artifacts are approved for promotion?
• did import/build succeed?
• do counts and outputs match the claims in the reports?
• is the final review packet complete enough for user approval?

It does not own:

• upstream generation or evaluation
• reader/browser verification ownership
• replay planning

Environment

Text data lives in the texts repository. Set LYCEUM_TEXTS_DIR to point to this directory (defaults to output/texts for local development).

The reader database is configured via LYCEUM_READER_DB (defaults to data/editions.db). Set this in .env to point at your lyceum reader's data/texts.db so promote imports directly into the reader.

Quick Status

Workspace importer: !ls scripts/import_workspace.go 2>/dev/null | wc -l Server build target: !ls cmd/server 2>/dev/null | wc -l Workspace review packs: !find ${LYCEUM_TEXTS_DIR:-output/texts} -path '*/qa/final-review-pack.md' 2>/dev/null | wc -l

Commands

• /new-text-ship preview [work] — Show what approved artifacts are ready for promotion and what is still blocking ship
• /new-text-ship promote [work] — Promote approved artifacts, run import/build steps, and record results
• /new-text-ship review-pack [work] — Assemble or refresh the final review packet
• /new-text-ship status [work] — Summarize promotion state, import/build results, and remaining blockers

Target: $ARGUMENTS

Owned Responsibilities

Owns

• promotion from approved workspace artifacts into shipped repo/DB artifacts
• import/build steps
• final review packet assembly
• final stop-before-silent-autopromotion behavior

Does not own

• deciding whether Stage 8 is semantically correct
• deciding whether Stage 9 passed reader QA
• replay planning or source-stage ownership

⚠️ URN Convention (Critical)

Do NOT manually set english_edition_urn, generated_edition_urn, or greek_edition_urn in manifest.json.

The import script (scripts/import_workspace.go) auto-generates edition URNs with the "versified" convention that the reader requires for row view:

• English URN pattern: <work_urn>.workspace-versified-eng1
• Greek URN pattern: <work_urn>.workspace-grc1

Why this matters:

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

Validation:

• import_workspace.go warns if manually-set URNs don't follow the convention
• The warning shows the correct auto-generated URN pattern
• If you see this warning, remove the manual URN fields from manifest.json

Leave all edition URN fields blank in manifest.json — the import script handles them automatically.

Canonical Promotion Path

The intended promotion path is:

1. stage owners produce artifacts
2. evaluators approve them
3. new-text-ship promotes/imports/builds
4. user reviews the final review packet

Hard rule

Do not promote artifacts that were not explicitly approved upstream.

Workflows

/new-text-ship preview

Inspect the workspace and report:

• which stages are approved
• which artifacts are ready to promote
• which blockers remain
• what import/build actions would run

/new-text-ship promote

Promote approved artifacts.

Typical steps

1. verify upstream approval state in state.json
2. copy or publish approved artifacts into their shipped locations
3. run required import steps
4. rebuild the server when needed
5. record import/build outputs
6. update state.json and replay/stage-history.json

Current repo-facing helpers

Workspace import (handles all structure types via manifest.json structure_type field):

nix-shell -p go --run "go run scripts/import_workspace.go --workspace $LYCEUM_TEXTS_DIR/<slug>"

The --db flag defaults to $LYCEUM_READER_DB (set in .env), which should point at your lyceum reader's data/texts.db. If not set, falls back to data/editions.db.

After successful import, the promote command automatically:

• Commits workspace changes to the texts repo (if $LYCEUM_TEXTS_DIR is a git repo)
• Records import results in workspace state

Server rebuild (in your lyceum checkout):

cd /path/to/lyceum && go build -o server ./cmd/server/

Schema requirements

The reader expects these columns/tables beyond what import_workspace.go creates:

• aligned_words.aligned_translation TEXT — empty for pipeline imports, used by some older data
• aligned_words.notes TEXT — empty for pipeline imports
• text_metadata table — used for fable grading; empty unless populated separately

If creating a fresh database, ensure these exist before importing.

Note: Bespoke import scripts (like import_aesop_fables.go) are no longer needed. import_workspace.go dispatches on the structure_type field in manifest.json:

• chapter-line (default) — for chapter.line refs like 1.5, 2.10
• fable-sentence — for fable.sentence refs like 1.1, 2.3 (Aesop style)
• book-section — for book.section.subseg refs like 1.5.1
• chapter-verse — for biblical chapter.verse refs
• section — for single-level refs like 1, 2, 3

Witness import

Witness translations are imported automatically when:

1. A witnesses/catalog.json exists (schema v2 with format field)
2. The witness has "reader-display" in its roles array
3. The witness file is readable in the declared format
4. ≥50% of witness references match Greek references (direct or parent-prefix)

The importer supports four witness formats: ref-text-tsv, ref-bracket-prose, structured-json, and chapters-json. See translation-witness/SKILL.md for format details.

Witnesses with <50% reference overlap are skipped with a warning — they are candidates for a future companion-panel display rather than segment-level import.

Important rule

Promotion is not “done” until import/build results match expectations and Stage 9 reliability has passed.

/new-text-ship review-pack

Assemble the final packet for human review.

Include

• exact sources used
• why they were chosen
• known limitations
• alignment mode used
• completeness metrics
• benchmark summaries
• screenshots or sampled evidence where relevant
• generated-translation disclaimers if relevant
• next suggested improvements if still partial

Output

• qa/final-review-pack.md

/new-text-ship status

Summarize:

• upstream approval state
• promotion history
• import/build results
• review-pack completeness
• whether the text is ready for explicit user approval

Outputs

Canonical outputs

$LYCEUM_TEXTS_DIR/<slug>/
├── qa/final-review-pack.md
├── state.json
└── replay/stage-history.json

Related repo outputs

• promoted artifacts in their shipped locations
• DB import logs/results
• rebuilt server binary when needed

Verification Contract

This skill follows the Stage 10 contract from docs/text-pipeline-skill-verification-2026-03-13.md.

Verify

• only approved artifacts were promoted
• import/build completed successfully
• final review pack is complete
• no accidental regression to existing data occurred

Minimum evidence

• promoted artifacts and import logs
• build output
• qa/final-review-pack.md

Pass criteria

• promotion source is traceable to approved workspace artifacts
• DB import counts match expected scope
• build succeeds
• review pack lists sources, limitations, metrics, and next-step recommendations

Failure examples

• artifacts promoted without evaluator approval
• import succeeds but counts do not match report claims
• review pack omits known weaknesses

Required next steps

Before declaring done:

• run or confirm reader-reliability verify <work> on the promoted text
• request explicit user approval rather than silently auto-closing the work

Verification

After completing this stage, run the automated verification script:

bash scripts/verify_stage_10.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