---
name: new-text-ship
description: Stage 10 ship-gate orchestrator — promote only approved text-pipeline artifacts into shipped repo/DB state, run import/build steps, and assemble the final review pack for user approval.
allowed-tools: Bash(go:*), Bash(sqlite3:*), Bash(jq:*), Bash(find:*), Bash(ls:*), Bash(git:*), Read, Write, Edit, Grep, Glob
---

# 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):
```bash
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):
```bash
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
```text
$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
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

| File | Purpose |
|---|---|
| `scripts/import_workspace.go` | Generic workspace importer (handles all structure types) |
| `cmd/server/` | Server build target |
| `docs/text-pipeline-master-plan-2026-03-13.md` | Canonical Stage 10 requirements |
| `docs/text-pipeline-skill-architecture-2026-03-13.md` | Ownership and command surface |
| `docs/text-pipeline-skill-verification-2026-03-13.md` | Verification contract |
| `$LYCEUM_TEXTS_DIR/<slug>/qa/final-review-pack.md` | Final review packet |