scriveno 2.0.5

package/commands/scr/sacred/verse-numbering.md

@@ -0,0 +1,103 @@
+---
+description: Manage verse/ayah/pasuk numbering systems. Handles differences between traditions (Masoretic vs. Septuagint numbering, Hafs vs. Warsh Quranic numbering, etc.)
+argument-hint: "[--system <system>] [--convert <from>-<to>] [--verify]"
+---
+
+# Verse numbering
+
+You manage verse numbering across tradition-specific systems. Different traditions number the same text differently -- Psalm 10 in the Hebrew Masoretic text is Psalm 10 in most English Bibles but part of Psalm 9 in the Greek Septuagint and Latin Vulgate. Quranic ayah counts differ between Hafs and Warsh transmissions.
+
+## Availability
+
+Sacred work types only. Requires at least one drafted unit.
+
+## Supported systems
+
+- **masoretic** -- Hebrew Bible (Jewish and most Protestant)
+- **septuagint** -- Greek Old Testament (Orthodox, some Catholic)
+- **vulgate** -- Latin (Catholic tradition)
+- **quranic_hafs** -- Hafs recitation (most common Quran numbering)
+- **quranic_warsh** -- Warsh recitation (North African Quran numbering)
+- **pali_canon** -- Theravada Buddhist numbering
+- **sanskrit_vedic** -- Vedic hymn numbering
+- **custom** -- User-defined numbering scheme
+
+## What to do
+
+### No arguments
+
+Show the current numbering system from config.json. List any drafted units and their current verse counts. Highlight any numbering inconsistencies (e.g., a unit has 40 verses in one place and 41 in another).
+
+### --system <system>
+
+Switch the project's verse numbering system. Warning: this is a significant change. Show the writer what will be renumbered and ask for confirmation. On yes, rewrite verse markers throughout drafted units and update `.manuscript/config.json` with top-level `verse_numbering_system`. For older projects that already contain `sacred.verse_numbering_system`, mirror the value there as a legacy compatibility field.
+
+### --convert <from>-<to>
+
+Generate a conversion table between two numbering systems. Useful for commentaries that need to reference both systems, or for translations aligning to a canonical target.
+
+Output format:
+
+```
+Genesis 31:55 (Masoretic) = Genesis 32:1 (Septuagint)
+Psalm 51:1 (English) = Psalm 51:3 (Hebrew)
+...
+```
+
+Save the conversion table to `.manuscript/verse-conversion-{from}-{to}.md` for reference.
+
+### --dual
+
+Show dual numbering side by side where two systems diverge. Useful for commentaries or translations that need to reference both systems:
+
+```
+Psalm 51:1 (English) / Psalm 51:3 (Hebrew Masoretic)
+Genesis 31:55 (Masoretic) / Genesis 32:1 (Septuagint)
+```
+
+Store numbering metadata in `.manuscript/verse-map.json` with entries mapping each verse to its equivalent in other systems. This JSON file enables automated conversion and export in any numbering system.
+
+### --verify
+
+Scan all drafted units and flag any verse numbering issues:
+- Non-sequential numbers (missing or duplicated)
+- References to verses that don't exist
+- Cross-references in CONCORDANCE.md that don't resolve
+- Verses split or merged in ways that don't match the configured system
+- Mixed systems in the same unit
+
+Produce a report with specific file:line locations.
+
+## Integration
+
+- Export commands use verse numbering for pagination, cross-reference rendering, and index generation
+- `/scr:sacred:concordance` and `/scr:sacred:cross-reference` use the numbering as primary keys
+- `/scr:sacred:annotation-layer` uses verse numbers as anchors -- annotations are tied to specific verses
+- Translation work must preserve the source numbering system (or explicitly convert)
+
+## 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
+
+Technical and exact. Verse numbering is a mechanical concern with theological consequences -- a misnumbered cross-reference is a research error. Precision over prose.

package/commands/scr/sacred-numbering-format.md

@@ -0,0 +1,103 @@
+---
+description: "Show verse numbering format for the active sacred tradition."
+argument-hint: "[--example <text>]"
+---
+
+# /scr:sacred-verse-numbering -- Tradition Verse Numbering Reference
+
+Show the verse numbering format for the active sacred tradition. Reads the tradition profile from the project's config and displays the numbering system with example citations.
+
+## Usage
+
+```
+/scr:sacred-verse-numbering [--example <text>]
+```
+
+If `--example <text>` is provided, format the given text as a citation in the tradition's numbering system.
+
+---
+
+### STEP 1: LOAD TRADITION
+
+Read top-level `tradition` from `.manuscript/config.json`. For older projects only, if top-level `tradition` is absent and `sacred.tradition` exists, use `sacred.tradition` as a legacy fallback.
+
+If `tradition` is absent or null:
+> **No tradition set.** Add `"tradition": "<slug>"` to `.manuscript/config.json` to use this command. Valid traditions: `catholic`, `orthodox`, `tewahedo`, `protestant`, `jewish`, `islamic-hafs`, `islamic-warsh`, `pali`, `tibetan`, `sanskrit`.
+
+Then **stop**.
+
+Validate the tradition slug against the accepted list:
+`catholic`, `orthodox`, `tewahedo`, `protestant`, `jewish`, `islamic-hafs`, `islamic-warsh`, `pali`, `tibetan`, `sanskrit`
+
+If the value is not in this list:
+> **Unknown tradition "{tradition}".** Valid values: `catholic`, `orthodox`, `tewahedo`, `protestant`, `jewish`, `islamic-hafs`, `islamic-warsh`, `pali`, `tibetan`, `sanskrit`.
+
+Then **stop**.
+
+Load `templates/sacred/{tradition}/manifest.yaml`.
+
+---
+
+### STEP 2: DISPLAY NUMBERING FORMAT
+
+From the loaded manifest, read:
+- `label` -- the tradition's human name
+- `numbering.format` -- the citation format (e.g. `chapter:verse`, `surah:ayah`, `nikaya:sutta`)
+- `numbering.separator` -- the separator character (e.g. `:` or `.`)
+
+Display the numbering reference:
+
+```
+Tradition: {label}
+Format:    {numbering.format}
+Separator: {numbering.separator}
+```
+
+Then provide 3 example citations using the tradition's format:
+
+| Tradition | Example 1 | Example 2 | Example 3 |
+|-----------|-----------|-----------|-----------|
+
+Use the following tradition-specific examples:
+
+- **catholic / orthodox / protestant / tewahedo**: `Genesis 1:1`, `Psalms 23:1`, `John 3:16`
+- **jewish**: `Genesis 1:1`, `Psalms 23:1`, `Isaiah 53:5`
+- **islamic-hafs / islamic-warsh**: `1:1` (Al-Fatihah:1), `2:255` (Al-Baqarah:255, the Throne Verse), `112:1` (Al-Ikhlas:1)
+- **pali**: `DN.1.1` (Digha Nikaya, Sutta 1, section 1), `MN.22.1`, `SN.35.1`
+- **tibetan**: `1:1`, `2:3`, `5:12`
+- **sanskrit**: `1:1`, `2:47`, `18:66`
+
+If `--example <text>` was provided, also display:
+> **Your citation formatted:** {text formatted as a citation in this tradition's style, e.g. inserting the separator between parts if the text contains numbers}
+
+---
+
+### STEP 3: APPROVAL BLOCK REMINDER (CONDITIONAL)
+
+If `approval_block.required` is `true` in the loaded manifest:
+> **Reminder:** This tradition requires a {approval_block.label} before publication. Run `/scr:front-matter` to generate the approval block scaffold.
+
+If `approval_block.required` is `false`: skip this step silently.
+
+## 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/save.md

@@ -0,0 +1,109 @@
+---
+description: Save your current work. Auto-generates a descriptive save message from context.
+argument-hint: "[optional message]"
+---
+
+# Save
+
+You are saving the writer's current work. Your job is to create a git commit with a writer-friendly message, without exposing any git terminology.
+
+## 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:
+   - Read `.manuscript/config.json` for `developer_mode`.
+   - If `developer_mode: false` (writer mode): silently run `git init` in the project root. No output about this.
+   - If `developer_mode: true`: tell the writer "Initializing version tracking for this project." then run `git init`.
+
+3. **Check for changes to save.** Run `git status --porcelain .manuscript/`. If nothing has changed:
+   - Look at the last entry in STATE.md "Last actions" table for the timestamp.
+   - Tell the writer: "Nothing new to save. Your last save was [timestamp from last action]."
+   - Stop here.
+
+4. **Read `.manuscript/STATE.md`** to determine context:
+   - Current stage (discuss/plan/draft/review/submit)
+   - Current unit name and number (from config.json `command_unit` and STATE.md `Current unit`)
+   - Last command run (from "Last actions" table)
+   - Record highlights from `.manuscript/RECORD.md` when present: open threads, next-unit obligations, and recent established items
+
+5. **Auto-generate the commit message** based on context:
+   - If the writer provided an optional message argument: `"Saved: {writer's message}"`
+   - After drafting (last command was `draft`): `"Saved after drafting {unit_name} {N}"`
+   - After review (last command was `editor-review`): `"Saved after editor review of {unit_name} {N}"`
+   - After revision (last command was `revise`): `"Saved after revising {unit_name} {N}"`
+   - After planning (last command was `plan`): `"Saved after planning {unit_name} {N}"`
+   - After discussion (last command was `discuss`): `"Saved after discussing {unit_name} {N}"`
+   - Default / manual save: `"Saved work in progress on {unit_name} {N}"`
+
+6. **Update STATE.md** "Last actions" table with a new row:
+   - Timestamp: current date/time
+   - Command: `save`
+   - Unit: current unit from STATE.md
+   - Outcome: the generated message
+
+7. **Regenerate `.manuscript/CONTEXT.md`** before staging. This file is the bootstrap any new session reads first. Use the `templates/CONTEXT.md` scaffold and fill every `{{TOKEN}}`:
+   - `{{LAST_UPDATED}}` -- ISO 8601 timestamp of this save
+   - `{{LAST_COMMAND}}` -- `/scr:save`
+   - `{{TITLE}}`, `{{WORK_TYPE}}` -- from `.manuscript/config.json`
+   - `{{PHASE}}`, `{{CURRENT_UNIT}}` -- from STATE.md (the values you computed in step 6)
+   - `{{RECENT_ACTIONS}}` -- the last 5 lines of `.manuscript/HISTORY.log` rendered as table rows. If HISTORY.log is missing, use the last 5 entries from STATE.md "Last actions" instead.
+   - `{{UNITS_PENDING_REVIEW}}`, `{{UNITS_PENDING_DRAFT}}`, `{{VOICE_WARNINGS}}`, `{{CONTINUITY_FLAGS}}`, `{{SCAFFOLD_MARKERS}}` -- from STATE.md "Pending"
+   - `{{RECORD_HIGHLIGHTS}}` -- a compact 3-5 line summary from RECORD.md: open threads, promises needing payoff, and next-unit obligations. If RECORD.md is missing, use `No RECORD.md found yet.`
+   - `{{NEXT_STEP}}` -- the same suggestion `/scr:next` would emit
+   - `{{LAST_SCAN}}`, `{{LAST_SCAN_VERDICT}}` -- from STATE.md if recorded; otherwise `never run` and `unknown`
+   Save to `.manuscript/CONTEXT.md`. This file is committed alongside STATE.md.
+
+8. **Append one line to `.manuscript/HISTORY.log`** per `docs/history-protocol.md`:
+   ```
+   {ISO timestamp} | scr:save | message="{generated message}" | files={changed file count} | outcome=committed
+   ```
+   If HISTORY.log does not exist, create it. Do not stage it as a separate operation -- step 9 picks it up.
+
+9. **Execute the save:**
+   ```
+   git add .manuscript/
+   git commit -m "{generated message}"
+   ```
+   This commit must include the `STATE.md`, `CONTEXT.md`, and `HISTORY.log` updates from steps 6 through 8 so the worktree is clean immediately after a successful save.
+
+10. **Tell the writer** the result (see output section below).
+
+## Writer mode output
+
+- **Writer mode** (`developer_mode: false`): "Saved. You can see your save history with `/scr:history`."
+- **Developer mode** (`developer_mode: true`): Show full git commit output including the short hash and message: "Committed: {hash} - {message}"
+
+## Edge cases
+
+- **No changes to save:** "Nothing new to save. Your last save was [timestamp]."
+- **Not in a Scriveno project** (no `.manuscript/` directory): "No manuscript found. Start with `/scr:new-work`."
+- **Git repo corrupted or in bad state:** In writer mode, say "Something went wrong saving your work. Try again, or ask for help." In developer mode, show the git error.
+- **Very first save** (no previous commits): Auto-generate message as "Initial save of {work title}" using the title from `.manuscript/WORK.md` if available.
+
+## 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
+
+Brief. Reassuring. The writer should feel that their work is safely stored. Don't explain what git did -- just confirm it's saved.

package/commands/scr/scan.md

@@ -0,0 +1,291 @@
+---
+description: Scan the project for context drift between recorded state and what is actually on disk.
+argument-hint: "[--fix] [--quiet]"
+---
+
+# /scr:scan -- Context Drift Scanner
+
+You are the project's drift detector. Trust nothing. Compare what `.manuscript/STATE.md`, `OUTLINE.md`, `RECORD.md`, `config.json`, and the various structural files **claim** against what the filesystem actually contains, and report every mismatch.
+
+This is the defense against context corruption. A fresh Claude session, a writer who hand-edited files between sessions, an interrupted command, or a partial revert can all leave the project in an internally inconsistent state. STATE.md says 12 units drafted; the disk has 14. OUTLINE.md lists "Chapter 8" but no draft file exists. RECORD.md says a promise is still open but the draft paid it off. STYLE-GUIDE.md was edited yesterday but no voice-check has run since. `/scr:scan` finds those.
+
+This complements `/scr:health` (which fixes structural issues like missing directories) and `/scr:resume-work` (which reads recorded state). `/scr:scan` interrogates whether the recorded state is true.
+
+## Usage
+
+```
+/scr:scan              # report-only
+/scr:scan --fix        # offer to fix the auto-fixable mismatches
+/scr:scan --quiet      # only show drift; suppress the all-clear summary
+```
+
+## Instruction
+
+Load `.manuscript/config.json`, `.manuscript/STATE.md`, `.manuscript/OUTLINE.md`, and `.manuscript/RECORD.md` when present. Each check below produces a finding with one of three severities:
+
+- **DRIFT** -- recorded state contradicts disk reality. Trust nothing downstream until resolved.
+- **WARNING** -- an artifact is stale or out of date. Downstream work may be silently using outdated input.
+- **INFO** -- worth noticing but not actionable.
+
+Run every check. Do not stop on first finding. Bundle them all into one report.
+
+---
+
+### CHECK 1: STATE.md unit counts vs. filesystem
+
+Read `STATE.md` for `Units drafted`, `Units planned`, `Units reviewed`, and `Total words`. Then count what is actually on disk:
+
+- **Units drafted** = files matching `.manuscript/drafts/body/*-DRAFT.md`
+- **Units planned** = files matching `.manuscript/*-*-PLAN.md` (numeric-prefixed plan files)
+- **Units reviewed** = files matching `.manuscript/*-EDITOR-NOTES.md`
+- **Total words** = `wc -w` summed across all `drafts/body/*-DRAFT.md` files
+
+For each metric where STATE.md value != filesystem value, emit:
+
+```
+DRIFT  STATE.md units-drafted = 12, on disk = 14 (delta +2)
+       Likely cause: drafts written outside /scr:draft, or STATE.md not updated.
+       Fix: re-run /scr:draft on the missing units, or update STATE.md to match disk.
+```
+
+For total words, allow a 10-word slack (writers tweak prose without re-saving).
+
+---
+
+### CHECK 2: OUTLINE.md units vs. draft files
+
+Parse `OUTLINE.md` for the ordered unit list. Compare against `.manuscript/drafts/body/`:
+
+- **Outline orphans** -- units listed in OUTLINE.md with no draft file. Severity: INFO if the unit was added recently and has no plan yet; DRIFT if a plan file exists but no draft.
+- **Draft orphans** -- draft files that do not appear in OUTLINE.md. Severity: DRIFT (an orphan draft will not be assembled at export time and the writer may not know).
+
+For each orphan, emit one finding with the unit identifier and the file path.
+
+---
+
+### CHECK 3: Plan vs. draft alignment
+
+For each `*-PLAN.md` file in `.manuscript/`, check whether the corresponding `*-DRAFT.md` exists in `drafts/body/`. If a plan exists but no draft:
+
+```
+INFO   Unit 8 has a plan ({N}-{A}-PLAN.md) but no draft yet.
+       Next: /scr:draft 8
+```
+
+For each draft, check whether the corresponding plan exists. If a draft exists but no plan:
+
+```
+WARNING Unit 12 was drafted without a plan file.
+        Drafter ran on inferred context. Voice check may be uneven.
+        Fix: backfill the plan via /scr:plan 12, or accept and move on.
+```
+
+---
+
+### CHECK 4: STYLE-GUIDE.md vs. last drafter run
+
+Compare the modification timestamp of `STYLE-GUIDE.md` against the modification timestamp of the **newest** `*-DRAFT.md` file in `drafts/body/`.
+
+If STYLE-GUIDE.md is newer than every draft file, voice DNA has changed since the last draft was written. Emit:
+
+```
+WARNING STYLE-GUIDE.md was edited at 2026-05-09T14:22:00Z
+        Newest draft: 12-B-DRAFT.md at 2026-05-08T11:05:00Z
+        Drafts written before the style guide edit may not reflect the current voice.
+        Fix: /scr:voice-check N for any unit drafted before 2026-05-09.
+```
+
+If the most recent voice-check run is recorded in STATE.md and is older than STYLE-GUIDE.md's edit, also flag.
+
+Use the appropriate stat command for the platform (per `/scr:export` STEP 1.6b conventions):
+- macOS: `stat -f %m <file>`
+- Linux: `stat -c %Y <file>`
+- Windows: `(Get-Item '<file>').LastWriteTimeUtc.Ticks`
+
+---
+
+### CHECK 5: Front-matter scaffolds still pending
+
+Scan `.manuscript/front-matter/*.md`. For each file with `scaffold: true` in its YAML header, emit:
+
+```
+INFO   Front matter element "12-preface.md" still has scaffold: true
+       It will be excluded from publication exports until you set scaffold: false.
+       Edit the file or run /scr:front-matter --element preface to draft it.
+```
+
+This is informational, not drift -- the scaffold gate is intentional.
+
+---
+
+### CHECK 6: Stale export outputs
+
+Scan `.manuscript/output/`. For each output file (`manuscript.pdf`, `manuscript.docx`, `manuscript.epub`, `manuscript-print.pdf`, etc.), compare its modification timestamp against the newest source file (any `drafts/body/*-DRAFT.md` or `front-matter/*.md` or `back-matter/*.md`).
+
+If any source is newer than the export, emit:
+
+```
+WARNING .manuscript/output/manuscript.epub is older than the newest draft.
+        Last exported: 2026-05-07T09:14:00Z
+        Newest source: drafts/body/12-B-DRAFT.md at 2026-05-09T16:42:00Z
+        Re-export: /scr:export --format epub
+```
+
+Group all stale outputs into one finding when the same source is newer than multiple outputs.
+
+---
+
+### CHECK 7: CONTEXT.md staleness
+
+If `.manuscript/CONTEXT.md` exists, compare its mtime against STATE.md and the newest draft. If CONTEXT.md is older than either, emit:
+
+```
+WARNING .manuscript/CONTEXT.md is older than the recorded state.
+        A fresh session reading CONTEXT.md will get an outdated picture.
+        Fix: /scr:resume-work to regenerate it (or /scr:scan --fix).
+```
+
+If CONTEXT.md does not exist, emit INFO with a one-line suggestion to run `/scr:resume-work` once to generate it.
+
+---
+
+### CHECK 8: HISTORY.log integrity
+
+If `.manuscript/HISTORY.log` exists, scan the last 50 lines for malformed entries (lines that don't match the pipe-delimited contract from `docs/history-protocol.md`). Report the count of malformed lines as INFO. Do not auto-fix.
+
+If HISTORY.log does not exist, emit INFO that history-tracking is not active.
+
+---
+
+### CHECK 9: Sacred-tradition config vs. shipped templates
+
+If `config.json` has a `tradition:` key set, verify that `templates/sacred/<tradition>/manifest.yaml` exists in the installed Scriveno templates. If not, emit:
+
+```
+DRIFT   config.json declares tradition: "{value}"
+        But templates/sacred/{value}/manifest.yaml does not exist.
+        Sacred-aware commands will fall back to defaults silently.
+        Fix: pick a shipped tradition (list via /scr:settings) or add the manifest.
+```
+
+---
+
+### CHECK 10: CHARACTERS.md vs. drafts
+
+Parse `.manuscript/CHARACTERS.md` (or FIGURES.md for sacred works) for character/figure names. Grep all draft files for proper-noun strings that look like character names (capitalized, two or more occurrences) but do not appear in CHARACTERS.md. Emit each unknown name as INFO with the first draft file it appears in:
+
+```
+INFO   "Marcus" appears in 4 drafts but is not in CHARACTERS.md.
+       Either add a character entry via /scr:new-character "Marcus", or this is a one-off mention.
+```
+
+This is best-effort. False positives (locations, brands, common nouns capitalized at sentence start) are expected. Group similar findings.
+
+---
+
+### CHECK 11: RECORD.md integrity
+
+If `.manuscript/RECORD.md` does not exist, emit INFO for older projects:
+
+```
+INFO   RECORD.md is missing.
+       This project can still work, but Scriveno has no compact store for what the work has established.
+       Fix: /scr:scan --fix can initialize RECORD.md from the installed template.
+```
+
+If RECORD.md exists, check it against drafted content as a compact best-effort audit:
+
+- **Staleness** -- If the newest draft is newer than RECORD.md and no later editor review or save mentions record updates, emit WARNING that RECORD.md may not include the latest established content.
+- **Empty store after drafts** -- If draft files exist but RECORD.md still contains only placeholders, emit WARNING.
+- **Resolved thread still marked open** -- If a thread is listed as open but review reports or later draft text clearly mark it resolved, emit INFO with a suggested update.
+- **Record contradiction** -- If a durable fact in RECORD.md directly contradicts a later draft, emit DRIFT and cite both locations when possible.
+
+Do not over-claim. RECORD.md is an interpretive store, so uncertain findings should be INFO or WARNING unless the contradiction is explicit.
+
+---
+
+### REPORT
+
+Output a single structured report:
+
+```
+Scriveno context scan
+====================
+Project: [title from config.json]
+Scanned: [N] checks across .manuscript/
+Findings: [X] drift, [Y] warnings, [Z] info
+
+DRIFT (must resolve before downstream commands can be trusted)
+--------------------------------------------------------------
+[finding 1 with fix command]
+[finding 2 with fix command]
+...
+
+WARNINGS (downstream may be using stale input)
+-----------------------------------------------
+[finding 1]
+[finding 2]
+...
+
+INFO (notice and move on if desired)
+-------------------------------------
+[finding 1]
+[finding 2]
+...
+```
+
+If there are zero findings AND `--quiet` was not passed, end with:
+
+> All checks passed. Recorded state matches disk reality.
+
+If `--quiet` was passed and there are zero findings, exit silently with no output.
+
+---
+
+### --fix MODE
+
+When `--fix` is passed, after the report, group findings by auto-fixability:
+
+- **Auto-fixable now** -- finding has a deterministic fix Scriveno can apply (e.g. update STATE.md unit counts to match disk, initialize missing RECORD.md from the installed template, regenerate stale CONTEXT.md, sort orphan drafts into a `_unsorted/` review directory). For each, ask the writer once:
+  > Apply [N] auto-fixes? (yes / no / show me what each does)
+- **Requires writer decision** -- finding needs a judgment call (e.g. character orphans, scaffold pending, voice drift). List with suggested next command.
+- **Manual** -- finding requires manual cleanup (e.g. malformed HISTORY.log lines).
+
+If the writer accepts auto-fixes, apply them in one batch and re-emit the affected findings as RESOLVED.
+
+After any auto-fix, append a single line to HISTORY.log per `docs/history-protocol.md`:
+
+```
+[ISO timestamp] | scr:scan --fix | files=STATE.md,CONTEXT.md | outcome=fixed-N
+```
+
+---
+
+## 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
+
+This command is the trust layer. Be precise, blunt, and actionable. Do not soften DRIFT findings into "you might want to consider" -- a drift finding means downstream commands cannot be trusted until resolved. Say so. WARNINGS should still be specific enough that the writer knows whether to act.
+
+A scan with zero drift findings is not noise. It is the writer earning the right to trust `/scr:next`, `/scr:export`, and `/scr:publish` for the rest of the session.