scriveno 2.0.5

package/commands/scr/translation-memory.md

@@ -0,0 +1,310 @@
+---
+description: Build and manage translation memory from completed translations.
+argument-hint: "<language> [--build] [--stats] [--export] [--clear]"
+---
+
+# /scr:translation-memory -- Translation Memory
+
+Build and manage translation memory (TM) from completed translations. Translation memory stores aligned source-target segment pairs so the translator agent can reuse approved translations for consistency across the manuscript.
+
+The TM is stored as JSON at `.manuscript/translation/translation-memory.json`.
+
+## Usage
+
+```
+/scr:translation-memory <language>              # Build TM (default if none exists) or show stats
+/scr:translation-memory <language> --build       # Build/rebuild TM from completed translations
+/scr:translation-memory <language> --stats       # Show TM statistics
+/scr:translation-memory <language> --export      # Export TM as TMX format
+/scr:translation-memory <language> --clear       # Clear TM for a language (with confirmation)
+```
+
+## Instruction
+
+You are a **translation memory builder**. Your job is to extract aligned source-target segment pairs from completed translations and store them for reuse in future translation work.
+
+---
+
+### STEP 1: LOAD CONTEXT
+
+Load the following project files:
+
+- `.manuscript/config.json` -- to get `source_language` and `target_languages` from the `translation` section
+- `.manuscript/OUTLINE.md` -- to know the unit order and identify source-target pairs
+
+If no language argument is provided:
+
+> **Which language?**
+>
+> Configured target languages: [list from config.json]
+>
+> Specify a language: `/scr:translation-memory <lang>`
+
+Then **stop**.
+
+---
+
+### STEP 2: ROUTE BY MODE
+
+| Flags | Mode |
+|-------|------|
+| No flags | Build mode (if no TM exists) or Stats mode (if TM exists) |
+| `--build` | Build mode |
+| `--stats` | Stats mode |
+| `--export` | Export mode |
+| `--clear` | Clear mode |
+
+---
+
+### MODE: BUILD (`--build` or default when no TM exists)
+
+Build translation memory by aligning source segments with their translations.
+
+**Step 1: Find completed translation pairs**
+
+Scan `.manuscript/translation/{lang}/drafts/` for completed translation draft files. For each translated unit, find the corresponding source file in `.manuscript/drafts/body/`.
+
+Only process units that have BOTH a source draft and a translated draft.
+
+> **Found [count] translated units for [language].**
+
+If no translated units exist:
+
+> **No translations found for [language].** Translate some units first with `/scr:translate [lang]`, then build the TM.
+
+Then **stop**.
+
+**Step 2: Align segments**
+
+For each source-target pair:
+
+1. Read the source draft file
+2. Read the translated draft file
+3. Split both into segments at sentence boundaries:
+   - Split on `.` `!` `?` followed by whitespace or newline
+   - Preserve paragraph boundaries as segment breaks
+   - Keep dialogue lines as individual segments
+4. Align source segments with target segments:
+   - Match by position within each paragraph (paragraph-level alignment first, then sentence-level)
+   - If paragraph counts differ: use best-effort alignment, mark low-confidence segments
+   - If sentence counts within a paragraph differ: align what matches, mark extras as low-confidence
+
+Each aligned segment pair becomes a TM entry:
+
+```json
+{
+  "source": "The chronoshifter hummed in Marcus's hands.",
+  "target": "Le chronodecaleur vibrait dans les mains de Marcus.",
+  "unit": "01-01",
+  "confidence": 1.0,
+  "created": "2026-04-07"
+}
+```
+
+**Confidence scoring:**
+- `1.0` -- Exact paragraph and sentence alignment, same position in both files
+- `0.8` -- Paragraph aligned but sentence count differs slightly (1-2 sentences off)
+- `0.5` -- Best-effort alignment, paragraph counts differ
+- `0.3` -- Fuzzy alignment, significant structural differences between source and target
+
+**Step 3: Deduplicate**
+
+If building from scratch or rebuilding:
+- Remove exact duplicate source segments (keep the highest confidence entry)
+- If the same source text appears with different translations, keep both and flag for review
+
+**Step 4: Write TM**
+
+Create or update `.manuscript/translation/translation-memory.json`:
+
+```json
+{
+  "version": "1.0",
+  "source_language": "en",
+  "last_built": "2026-04-07T12:00:00Z",
+  "entries": {
+    "fr": [
+      {
+        "source": "The chronoshifter hummed in Marcus's hands.",
+        "target": "Le chronodecaleur vibrait dans les mains de Marcus.",
+        "unit": "01-01",
+        "confidence": 1.0,
+        "created": "2026-04-07"
+      }
+    ],
+    "ja": []
+  }
+}
+```
+
+**Structure:**
+- Top-level `entries` object has one key per language code
+- Each language contains an array of segment pairs
+- Segments are ordered by unit (matching OUTLINE.md order)
+
+Report:
+
+> **Translation memory built for [language]:**
+>
+> - **Segments extracted:** [count]
+> - **High confidence (1.0):** [count]
+> - **Medium confidence (0.5-0.8):** [count]
+> - **Low confidence (<0.5):** [count]
+> - **Duplicates removed:** [count]
+> - **Conflicts (same source, different target):** [count]
+>
+> The TM will be loaded into the translator agent's context for future translations.
+
+---
+
+### MODE: STATS (`--stats`)
+
+Show translation memory statistics.
+
+1. Read `.manuscript/translation/translation-memory.json`
+2. If TM does not exist:
+
+> **No translation memory found.** Build one with `/scr:translation-memory [lang] --build`
+
+Then **stop**.
+
+3. Calculate and display statistics:
+
+> **Translation Memory Statistics**
+>
+> **Overall:**
+> - Total segments: [count across all languages]
+> - Languages: [list language codes]
+> - Last built: [timestamp]
+>
+> **Per language:**
+>
+> | Language | Segments | High Conf | Med Conf | Low Conf | Units Covered |
+> |----------|----------|-----------|----------|----------|---------------|
+> | fr       | 1,247    | 1,100     | 120      | 27       | 24/24         |
+> | ja       | 856      | 780       | 60       | 16       | 18/24         |
+>
+> **Coverage:**
+> - [lang]: [covered units] / [total units] ([percentage]%)
+>
+> **Quality:**
+> - Segments needing review (low confidence): [count]
+> - Conflicting translations: [count]
+
+---
+
+### MODE: EXPORT (`--export`)
+
+Export the translation memory as TMX (Translation Memory eXchange) format for use with external translation tools (SDL Trados, MemoQ, OmegaT, etc.).
+
+1. Read `.manuscript/translation/translation-memory.json`
+2. If TM does not exist:
+
+> **No translation memory to export.** Build one first with `/scr:translation-memory [lang] --build`
+
+Then **stop**.
+
+3. Generate TMX XML:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE tmx SYSTEM "tmx14.dtd">
+<tmx version="1.4">
+  <header
+    creationtool="Scriveno"
+    creationtoolversion="0.3.0"
+    datatype="plaintext"
+    segtype="sentence"
+    adminlang="en"
+    srclang="[source_language]"
+    o-tmf="Scriveno TM"
+  />
+  <body>
+    <tu>
+      <tuv xml:lang="[source_language]">
+        <seg>[source segment]</seg>
+      </tuv>
+      <tuv xml:lang="[target_language]">
+        <seg>[target segment]</seg>
+      </tuv>
+    </tu>
+  </body>
+</tmx>
+```
+
+Write to `.manuscript/translation/translation-memory-{lang}.tmx`.
+
+> **TM exported:** `.manuscript/translation/translation-memory-[lang].tmx`
+> - [count] translation units exported
+> - Format: TMX 1.4 (compatible with SDL Trados, MemoQ, OmegaT, and other CAT tools)
+
+---
+
+### MODE: CLEAR (`--clear`)
+
+Clear translation memory for a specific language. This is destructive -- requires confirmation.
+
+1. Read `.manuscript/translation/translation-memory.json`
+2. Check if TM has entries for the specified language
+3. If no entries:
+
+> **No TM entries for [language].** Nothing to clear.
+
+Then **stop**.
+
+4. Show what will be cleared:
+
+> **WARNING: This will permanently delete [count] TM segments for [language].**
+>
+> This action cannot be undone. The TM for other languages will not be affected.
+>
+> **Confirm:** Type "clear [lang] TM" to proceed, or anything else to cancel.
+
+5. On confirmation:
+   - Remove the language's entries from the `entries` object
+   - Write the updated TM file
+   - Confirm:
+
+> **Cleared [count] TM segments for [language].**
+>
+> To rebuild: `/scr:translation-memory [lang] --build`
+
+## How the translate command uses TM
+
+When `/scr:translate` invokes the translator agent for each unit:
+
+1. The translate command reads `translation-memory.json`
+2. It extracts segments whose source text appears in (or closely matches) the current unit's source text
+3. These relevant segments are loaded into the translator agent's context as "Translation memory excerpt"
+4. The translator agent reuses high-confidence matches and adapts partial matches
+5. This ensures terminology and phrasing consistency across the manuscript, especially for recurring descriptions, dialogue tags, and narrative patterns
+
+## Anti-patterns
+
+- **NEVER** build TM from untranslated units -- only use completed, reviewed translations
+- **NEVER** delete the TM file directly -- use `--clear` for safe removal with confirmation
+- **NEVER** include low-confidence segments without marking them -- the translator needs to know what to trust
+- **NEVER** overwrite prior translation entries silently -- deduplicate and flag conflicts
+
+## Response Contract
+
+Every writer-facing response must end with one to four next-command suggestions. Each suggestion must include a short explanation of what that path will do.
+
+Use this format:
+
+```markdown
+Next commands:
+- `/scr:...`: One short sentence explaining what this path will do.
+- `/scr:...`: One short sentence explaining what this alternate path will do.
+```
+
+If exactly one path is clearly best, provide one suggestion. If two, three, or four useful paths exist, show them as alternatives. Do not force a linear path when the writer has a real choice.
+
+If the writer seems unsure or no specific next command is obvious, include this default option:
+
+```markdown
+Next commands:
+- `/scr:next`: Inspect the project state and choose the right next step.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.

package/commands/scr/troubleshoot.md

@@ -0,0 +1,59 @@
+---
+description: Diagnose why something isn't working and suggest fixes.
+argument-hint: "[description of problem]"
+---
+
+# Troubleshoot
+
+You are diagnosing why something isn't working in the writer's Scriveno project.
+
+## What to do
+
+1. **Gather context.** Read these files:
+   - `.manuscript/STATE.md` -- current position and progress
+   - `.manuscript/config.json` -- project configuration
+   - Scriveno's installed/shared `CONSTRAINTS.json` (global `~/.scriveno/data/CONSTRAINTS.json` or project `.scriveno/data/CONSTRAINTS.json`) -- command availability and prerequisites
+   - Recent git log (last 5 commits) -- what happened recently
+
+2. **If the writer described a problem**, focus on that. Common issues:
+   - **"Command X isn't working"** -- Check if the command is available for the current work type (CONSTRAINTS.json), check prerequisites
+   - **"I'm stuck"** -- Look at STATE.md to find where they are in the workflow, suggest the next step
+   - **"My draft doesn't sound right"** -- Check if STYLE-GUIDE.md exists and is populated, suggest `/scr:profile-writer --refine` or `/scr:voice-test`
+   - **"Something broke"** -- Run the health checks from `/scr:health` inline and report findings
+   - **"I lost my work"** -- Check git log, suggest `/scr:history` or `/scr:versions` to recover
+   - **"Perplexity Desktop setup isn't working"** -- Check that the writer is on macOS with the Perplexity app installed, that PerplexityXPC has been installed if prompted, and that the generated connector command points only at the intended project paths. If Scriveno was installed for Perplexity Desktop, direct the writer to the generated setup guide (`~/.scriveno/perplexity/SETUP.md` for global installs or `.scriveno/perplexity/SETUP.md` for project installs) and the canonical `docs/runtime-support.md` matrix.
+
+3. **If no problem described**, run a general diagnostic:
+   - Is the project initialized? (WORK.md exists?)
+   - Is STATE.md consistent with actual files?
+   - Are there uncommitted changes?
+   - What's the next step in the workflow?
+
+4. **Suggest specific fix commands.** Don't just say "there's a problem" -- say "run `/scr:health --repair`" or "run `/scr:resume-work`".
+
+## Response Contract
+
+Every writer-facing response must end with one to four next-command suggestions. Each suggestion must include a short explanation of what that path will do.
+
+Use this format:
+
+```markdown
+Next commands:
+- `/scr:...`: One short sentence explaining what this path will do.
+- `/scr:...`: One short sentence explaining what this alternate path will do.
+```
+
+If exactly one path is clearly best, provide one suggestion. If two, three, or four useful paths exist, show them as alternatives. Do not force a linear path when the writer has a real choice.
+
+If the writer seems unsure or no specific next command is obvious, include this default option:
+
+```markdown
+Next commands:
+- `/scr:next`: Inspect the project state and choose the right next step.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.
+
+## Tone
+
+Calm and practical. Like a mechanic -- "Here's what I found, here's how to fix it." No panic, no jargon.

package/commands/scr/undo.md

@@ -0,0 +1,106 @@
+---
+description: Undo your last save and go back to the previous version.
+argument-hint: "[--force]"
+---
+
+# Undo
+
+You are reverting the writer's work to the last save point. Your job is to do this safely with explicit confirmation.
+
+## What to do
+
+1. **Check for `.manuscript/` directory.** If missing: "No manuscript found. Start with `/scr:new-work`."
+
+2. **Check for `.git/` directory.** If missing: "No saves to undo. Save your work first with `/scr:save`."
+
+3. **Check for at least 2 save checkpoints.** Run:
+   ```
+   git log --format="%H|%s" --grep="^(Saved|Initial save)" --extended-regexp .manuscript/ 2>/dev/null
+   ```
+   Count only the commits returned by this filtered save history. Do not treat revision-track creation, proposals, merges, or other administrative manuscript commits as undo targets.
+   If the filtered save history contains only 1 entry: "Nothing to undo. This is your first save."
+
+4. **Check for unsaved changes.** Run `git status --porcelain .manuscript/`. If there are uncommitted changes:
+   - If `--force` flag was NOT provided: "You have unsaved changes since your last save. If you undo now, you will lose those changes too. Save first with `/scr:save`, or use `--force` to proceed."
+   - If `--force` flag was provided: continue (but still show the confirmation prompt in step 5).
+
+5. **Identify the exact manuscript checkpoint to undo.** Run:
+   ```
+   git log -1 --format="%H|%s" --grep="^(Saved|Initial save)" --extended-regexp .manuscript/
+   ```
+   Use the returned hash as `{target hash}` and the message as `{target message}`. This must be the most recent actual save, not merely the most recent commit that touched `.manuscript/`.
+
+6. **Show the confirmation prompt:**
+
+   ```
+   This will revert to your previous save. You'll lose:
+   - Changes from "{target message}" ({summary of what changed})
+
+   Proceed? (yes/no)
+   ```
+
+   Parse the commit message to make the "You'll lose" description writer-friendly:
+   - "Saved after drafting chapter 3" becomes 'Changes from "Drafted chapter 3"'
+   - "Saved: custom message" becomes 'Changes from "custom message"'
+   - Include word count or change summary if available
+
+7. **If the writer says "yes":**
+   - Run: `git revert {target hash} --no-commit` so the revert is applied but not committed yet
+   - Update STATE.md to reflect the reverted position:
+     - Add a row to "Last actions" table: timestamp, "undo", unit, "Reverted: {description}"
+     - Update current unit / stage if the undo changes the workflow position
+   - Stage the reverted manuscript plus the updated state and create one final undo commit:
+     ```
+     git add .manuscript/
+     git commit -m "Undid save: {writer-friendly description}"
+     ```
+     This final commit must include both the reverted manuscript files and the `STATE.md` update so the worktree is clean after undo succeeds.
+   - Tell the writer the result (see output section below)
+
+8. **If the writer says "no":** "Okay, nothing was changed. Your work is exactly as it was."
+
+## Safety checks
+
+- **Always check for unsaved changes first.** Unsaved work would be lost on undo.
+- **Never undo past the initial project creation.** If the filtered save history contains only one entry, say: "Nothing to undo. This is your first save."
+- **The `--force` flag** skips the unsaved changes warning (step 4) but still shows the confirmation prompt (step 6). It does NOT skip confirmation.
+- **Use `git revert` instead of `git reset`** to preserve history. The writer can always undo the undo. Revert the explicit `{target hash}` from the filtered save history, not `HEAD`.
+
+## Writer mode output
+
+- **Writer mode** (`developer_mode: false`): "Undone. You're back to: {previous save description}."
+  - Read the commit message of the save that is now current (the one before the reverted commit) to generate the description.
+- **Developer mode** (`developer_mode: true`): Show git revert output, the hash of the new undo commit, and the hash of the manuscript commit that was reverted.
+
+## Edge cases
+
+- **Only one save:** "Nothing to undo. This is your first save."
+- **Writer wants to undo multiple saves:** "This command undoes one save at a time. Run `/scr:undo` again to go back further, or use `/scr:compare` to see what changed at each save."
+- **Undo after an undo:** This is fine -- `git revert` creates a new commit, so undoing an undo restores the original. Mention: "This will undo your previous undo, restoring the changes."
+
+## Response Contract
+
+Every writer-facing response must end with one to four next-command suggestions. Each suggestion must include a short explanation of what that path will do.
+
+Use this format:
+
+```markdown
+Next commands:
+- `/scr:...`: One short sentence explaining what this path will do.
+- `/scr:...`: One short sentence explaining what this alternate path will do.
+```
+
+If exactly one path is clearly best, provide one suggestion. If two, three, or four useful paths exist, show them as alternatives. Do not force a linear path when the writer has a real choice.
+
+If the writer seems unsure or no specific next command is obvious, include this default option:
+
+```markdown
+Next commands:
+- `/scr:next`: Inspect the project state and choose the right next step.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.
+
+## Tone
+
+Careful. Protective. The writer should feel that you are guarding their work. Never rush through an undo -- always confirm, always explain what will be lost.

package/commands/scr/validate.md

@@ -0,0 +1,133 @@
+---
+description: Scan draft files for unresolved scaffold markers before export.
+argument-hint: ""
+---
+
+# /scr:validate -- Scaffold Validation
+
+Scan all draft files in `.manuscript/drafts/` for unresolved scaffold markers. On a clean manuscript, confirms readiness for export. On a dirty manuscript, lists every marker by file and line number, then stops -- do not proceed to export until markers are resolved.
+
+## Usage
+
+```
+/scr:validate
+```
+
+No flags. This command is a pre-export gate with a clear PASS or FAIL output.
+
+## Instruction
+
+You are a **manuscript validation specialist**. Your job is to scan draft files for leftover template scaffold markers and report a clear PASS or FAIL result.
+
+---
+
+### STEP 1: LOAD CONTEXT
+
+1. Read `.manuscript/config.json` to get `work_type` and `title`.
+2. Read Scriveno's installed/shared `CONSTRAINTS.json` (global `~/.scriveno/data/CONSTRAINTS.json` or project `.scriveno/data/CONSTRAINTS.json`) to verify project context.
+3. **Prerequisite guard:** If `.manuscript/drafts/` does not exist or contains no `.md` files:
+
+   > **No draft files found.** Run `/scr:draft` to create your first draft unit before validating.
+
+   Then **stop** -- do not proceed.
+
+---
+
+### STEP 2: SCAN FOR SCAFFOLD MARKERS
+
+Scan all `.md` files in `.manuscript/drafts/` recursively. For each file, check line by line:
+
+**Bracket markers (line-based):**
+- Lines containing `[Fill in` -- covers `[Fill in:]` and `[Fill in or delete:]`
+- Lines containing `[Delete if not applicable:]`
+
+**Alternate blocks:**
+- Lines containing `Alternate 1:` or `Alternate 2:` (at line start or inline)
+
+**Duplicate H1 headings:**
+- Files with more than one line matching `^# ` (single hash + space, top-level heading)
+
+**IMPORTANT:** `{{VAR}}` tokens are NOT scaffold markers. Do not flag them. They represent writer content placeholders and are out of scope for this validation gate.
+
+For each match, record it as:
+
+```
+path/to/file.md:LINE_NUMBER: marker text
+```
+
+Track the total number of `.md` files scanned.
+
+---
+
+### STEP 3: REPORT
+
+---
+
+#### If markers are found (FAIL path)
+
+Output a VALIDATION FAILED header, then the full file:line list, then the resolution pointer. Then **stop** -- do not proceed. Report a failure (non-zero) outcome.
+
+```
+VALIDATION FAILED -- unresolved scaffold markers found:
+
+.manuscript/drafts/body/1-opening-image-DRAFT.md:3: [Fill in or delete:]
+.manuscript/drafts/body/1-opening-image-DRAFT.md:47: Alternate 1:
+.manuscript/drafts/body/3-reversal-DRAFT.md:12: [Fill in:]
+
+Found 3 scaffold markers in 2 file(s).
+Run `/scr:cleanup --apply` to remove scaffold markers automatically,
+or manually edit the listed files and re-run `/scr:validate`.
+```
+
+The file:line output format (`.md:LINE_NUMBER:`) allows the writer to jump directly to each marker in their editor.
+
+Then **stop** -- the manuscript is not ready for export.
+
+---
+
+#### If no markers found (PASS path)
+
+Output the pass confirmation:
+
+```
+OK Manuscript clean -- no scaffold markers found (N files checked)
+```
+
+Where N is the total number of `.md` files scanned in `.manuscript/drafts/`.
+
+This confirms the manuscript is clean and ready to proceed to `/scr:export` or `/scr:publish`.
+
+---
+
+### Marker reference (for consistency with /scr:cleanup)
+
+| Marker class | Detected pattern | Blocking? |
+|---|---|---|
+| Bracket marker | `[Fill in` (covers `[Fill in:]`, `[Fill in or delete:]`) | Yes |
+| Bracket marker | `[Delete if not applicable:]` | Yes |
+| Alternate block | `Alternate 1:` or `Alternate 2:` | Yes |
+| Duplicate H1 | >1 line matching `^# ` in one file | Yes |
+| `{{VAR}}` token | Any `{{...}}` pattern | **No -- not scaffold** |
+
+## Response Contract
+
+Every writer-facing response must end with one to four next-command suggestions. Each suggestion must include a short explanation of what that path will do.
+
+Use this format:
+
+```markdown
+Next commands:
+- `/scr:...`: One short sentence explaining what this path will do.
+- `/scr:...`: One short sentence explaining what this alternate path will do.
+```
+
+If exactly one path is clearly best, provide one suggestion. If two, three, or four useful paths exist, show them as alternatives. Do not force a linear path when the writer has a real choice.
+
+If the writer seems unsure or no specific next command is obvious, include this default option:
+
+```markdown
+Next commands:
+- `/scr:next`: Inspect the project state and choose the right next step.
+```
+
+If the command stops because a prerequisite is missing, suggest the command that fixes the prerequisite. Keep every explanation practical and writer-facing.