scriveno 2.0.5

package/docs/architecture.md

@@ -0,0 +1,425 @@
+# Scriveno Architecture
+
+How Scriveno works under the hood -- for developers who want to understand the system before extending it.
+
+## Overview
+
+Scriveno is a pure skill system. There is no compiled code, no runtime library, no framework. AI coding agents (Claude Code, Cursor, Gemini CLI, and others) read markdown command files and follow their instructions using their built-in tools (Read, Write, Bash).
+
+The entire system is a collection of files:
+
+- **Command files** tell the agent what to do when a writer invokes `/scr:draft` or `/scr:new-work`
+- **Agent files** provide specialized instructions for tasks like drafting and voice-checking
+- **CONSTRAINTS.json** is the central registry that controls which commands are available for which work types
+- **Templates** provide starting content for new projects
+
+Nothing compiles. Nothing bundles. Changes take effect immediately because the agent reads files at runtime.
+
+## Skill System Design
+
+The skill system works like this:
+
+1. The writer types a slash command (e.g., `/scr:draft 3`)
+2. The AI agent reads `commands/scr/draft.md`
+3. The command file contains step-by-step instructions in plain markdown
+4. The agent follows those instructions, using its tools to read files, write drafts, and run checks
+
+Each command file has YAML frontmatter (metadata) and a markdown body (instructions):
+
+```yaml
+---
+description: Draft the planned unit. Invokes the drafter agent in fresh context.
+argument-hint: "[unit number, optional]"
+---
+
+# Draft {unit}
+
+You are orchestrating the drafter agent to produce the actual prose...
+
+## What to do
+
+1. Find all plan files for the unit...
+2. For each atomic unit, invoke the drafter agent in fresh context...
+3. Save drafted output...
+```
+
+The agent reads this file and executes it. No SDK, no API calls, no imports. The markdown IS the program.
+
+### Why markdown?
+
+- **Portability.** Any AI agent that can read files can run Scriveno
+- **No build step.** Contributors edit a `.md` file and the change is live
+- **Inspectable.** The writer can read any command file to understand exactly what Scriveno will do
+- **No dependencies.** No node_modules, no pip install, no version conflicts
+
+## CONSTRAINTS.json Schema
+
+`data/CONSTRAINTS.json` is the central registry. Every command checks it at runtime to determine what is available, what adapts, and what is restricted. Here are the top-level sections.
+
+### work_type_groups
+
+Groups related work types together. Commands use these groups for availability:
+
+```json
+"work_type_groups": {
+  "prose": {
+    "label": "Prose",
+    "members": ["novel", "novella", "short_story", "flash_fiction",
+                "memoir", "creative_nonfiction", "biography", "essay",
+                "essay_collection"]
+  },
+  "sacred": {
+    "label": "Sacred & Historical",
+    "members": ["scripture_biblical", "scripture_quranic", "commentary",
+                "devotional", "liturgical", "historical_chronicle", ...]
+  }
+}
+```
+
+There are 9 groups: prose, script, academic, technical, visual, poetry, interactive, speech_song, and sacred. Together they contain 50 work types.
+
+### work_types
+
+Individual work type definitions. Each entry specifies its structural hierarchy and which hierarchy level commands operate on:
+
+```json
+"novel": {
+  "label": "Novel",
+  "group": "prose",
+  "hierarchy": { "top": "part", "mid": "chapter", "atomic": "scene" },
+  "command_unit": "chapter"
+}
+```
+
+- **`hierarchy`** -- Three structural levels. The `top` is the largest division (part, act, testament), `mid` is the middle (chapter, scene, section), and `atomic` is the smallest unit that gets drafted individually (scene, beat, verse).
+- **`command_unit`** -- Determines how commands adapt their terminology. A novel's `/scr:draft` talks about drafting a chapter. A screenplay's `/scr:draft` talks about drafting an act.
+
+Sacred work types can also specify defaults:
+
+```json
+"scripture_quranic": {
+  "label": "Scripture (Quranic)",
+  "group": "sacred",
+  "hierarchy": { "top": null, "mid": "surah", "atomic": "ayah" },
+  "command_unit": "surah",
+  "config_defaults": {
+    "verse_numbering_system": "quranic_hafs",
+    "calendar_system": "hijri"
+  }
+}
+```
+
+### commands
+
+The command registry. Each entry maps a command name to its category, availability, and behavior:
+
+```json
+"draft": {
+  "category": "core",
+  "available": ["all"],
+  "renames_by_unit": true,
+  "description": "Draft the planned unit"
+},
+"editor-review": {
+  "category": "core",
+  "available": ["all"],
+  "adapted": {
+    "academic": { "rename": "peer-review" },
+    "sacred": { "rename": "scholarly-review" }
+  },
+  "description": "Manual review of drafted unit"
+}
+```
+
+- **`available`** -- `["all"]` means universal. Otherwise, list specific group names like `["prose", "script"]`.
+- **`renames_by_unit`** -- Legacy schema flag indicating that the command's terminology adapts based on the project's `command_unit`. The runnable command id remains the canonical base command.
+- **`adapted`** -- Per-group overrides. The `editor-review` command becomes `peer-review` for academic works, `technical-review` for technical docs, and `scholarly-review` for sacred works.
+
+## File Structure
+
+```
+scriveno/
+  commands/
+    scr/                   Core command tree (100+ command files total, including sacred subcommands)
+      draft.md             Core workflow: draft a unit
+      new-work.md          Core workflow: start a new project
+      autopilot.md         Autonomous pipeline orchestrator
+      help.md              Navigation: show available commands
+      ...
+      sacred/              8 sacred-exclusive subcommands
+        concordance.md
+        cross-reference.md
+        ...
+  agents/
+    drafter.md             Drafts one atomic unit in the writer's voice
+    voice-checker.md       Compares drafts against STYLE-GUIDE.md
+    continuity-checker.md  Catches contradictions and timeline errors
+    plan-checker.md        Validates unit plans before drafting
+    researcher.md          Gathers research material
+    translator.md          Translates content with voice preservation
+  data/
+    CONSTRAINTS.json       Central constraint registry (the source of truth)
+    demo/                  Pre-baked demo project (watchmaker story)
+    export-templates/      Output format templates
+      scriveno-book.typst     Book interior PDF
+      scriveno-epub.css       EPUB styling
+      scriveno-academic.latex Academic paper formatting
+    templates/
+    config.json            Per-project configuration template
+    WORK.md                Work overview template
+    OUTLINE.md             Structural outline template
+    RECORD.md              Established content store template
+    CHARACTERS.md          Character profiles template
+    STYLE-GUIDE.md         Voice DNA template
+    WRITING-RULES.md       Universal AI-tell rulebook (1.6.0+)
+    THEMES.md              Thematic threads template
+    STATE.md               Progress tracking template
+    BRIEF.md               Project brief template
+    WORLD.md               World-building template
+    pitfalls/              Per-work-type pitfall packs (1.6.0+)
+      novel.md, memoir.md, screenplay.md, runbook.md,
+      research_paper.md, poetry_collection.md, comic.md,
+      commentary.md (drop-in extensible: contributors add
+      <work_type>.md and listPitfallPacks() picks it up)
+    technical/             Technical-writing template variants
+      DOC-BRIEF.md           Replaces BRIEF.md for technical docs
+      AUDIENCE.md            Reader and audience contract
+      DEPENDENCIES.md        Systems, owners, and interface map
+      SYSTEM.md              Replaces WORLD.md for technical docs
+      PROCEDURES.md          Replaces PLOT-GRAPH.md for technical docs
+      REFERENCES.md          Replaces THEMES.md for technical docs
+    sacred/                Sacred-specific templates
+      FIGURES.md             Replaces CHARACTERS.md for sacred works
+      DOCTRINES.md           Theological framework
+      COSMOLOGY.md           World/cosmological structure
+      LINEAGES.md            Genealogies and lineage tracking
+      FRAMEWORK.md           Interpretive framework
+      THEOLOGICAL-ARC.md     Replaces PLOT-GRAPH.md for sacred works
+  bin/
+    install.js             Multi-platform installer (Node.js)
+  docs/
+    proof-artifacts.md     Canonical proof layer and artifact index
+    getting-started.md     Install to first draft in 10 minutes
+    command-reference.md   Full command listing with usage
+    work-types.md          50 work types and how they adapt Scriveno
+    voice-dna.md           Voice profile system guide
+    publishing.md          Export formats and publishing pipelines
+    sacred-texts.md        Sacred work types and voice registers
+    translation.md         Translation pipeline guide
+    contributing.md        How to extend Scriveno (commands, agents, etc.)
+    configuration.md       Package, installer, constraints, and project config surfaces
+    development.md         Contributor workflow for changing Scriveno itself
+    testing.md             Test suite coverage and release-safety checks
+    shipped-assets.md      Canonical shipped-template and trust-file inventory
+    runtime-support.md     Canonical runtime matrix and Node baseline
+    release-notes.md       Public package-release summaries
+    architecture.md        This file
+  .manuscript/             Per-project working directory (created by commands)
+```
+
+The `.manuscript/` directory is created when a writer runs `/scr:new-work`. It contains their project's context files (STYLE-GUIDE.md, OUTLINE.md, RECORD.md, CHARACTERS.md, etc.), plans, drafts, and state. It is not shipped with Scriveno -- it is generated per project.
+
+## Creative Context
+
+Scriveno context files can include optional Creative Context metadata that helps commands route project memory without changing the historical file contract. See [Creative Context](creative-context.md) for the full pilot protocol.
+
+The important rule is unchanged: `STYLE-GUIDE.md` is sovereign and loads first for any prose-producing task. Other metadata is advisory. Existing projects without frontmatter still work through the established filenames.
+
+## Agent Orchestration
+
+Commands invoke agents to perform specialized work. Here is how the orchestration flows:
+
+```
+Writer: /scr:draft 3
+        |
+        v
+  commands/scr/draft.md
+  (orchestration command)
+        |
+        |  For each atomic unit (scene):
+        |
+        v
+  agents/drafter.md          <-- fresh context per unit
+  receives: STYLE-GUIDE.md, 3-1-PLAN.md, CHARACTERS.md excerpt,
+            previous unit tail (200 words), THEMES.md excerpt
+  produces: .manuscript/drafts/body/3-1-DRAFT.md
+        |
+        v
+  agents/voice-checker.md    <-- fresh context
+  receives: STYLE-GUIDE.md, .manuscript/drafts/body/3-1-DRAFT.md
+  produces: voice score + issues list
+        |
+        v
+  draft.md updates STATE.md, reports to writer
+```
+
+The autopilot command (`/scr:autopilot`) chains multiple stages:
+
+```
+/scr:autopilot
+    |
+    FOR each unit in OUTLINE.md:
+    |
+    +-> /scr:discuss N
+    +-> /scr:plan N
+    +-> /scr:draft N
+    |     +-> drafter agent (per atomic unit)
+    |     +-> voice-checker agent
+    +-> /scr:editor-review N
+    +-> /scr:submit N
+    |
+    Pause behavior depends on profile:
+      guided     -> pause after every atomic unit
+      supervised -> pause at structural boundaries
+      full-auto  -> pause only on errors
+```
+
+Key points:
+
+- Commands are orchestrators. They read instructions and coordinate work.
+- Agents are workers. They receive specific files and produce specific output.
+- Each agent invocation is independent. No shared state between invocations.
+- STYLE-GUIDE.md is always the first file loaded into any agent that produces or evaluates prose.
+
+## Fresh Context per Unit
+
+This is the core architectural pattern that makes Scriveno work. Every agent invocation starts with a clean context -- no prior conversation, no accumulated state, no cross-contamination.
+
+### Why fresh context?
+
+**Voice drift.** When an AI accumulates context across multiple scenes, its writing style gradually shifts. By scene 10, it no longer sounds like the writer -- it sounds like an average of everything it has read. Fresh context forces the agent to re-read STYLE-GUIDE.md every time, resetting the voice profile.
+
+**Context bloat.** A 100,000-word novel would overwhelm the agent's context window if loaded all at once. Fresh context means each unit works within comfortable limits.
+
+**Focus.** The agent receives only what it needs for this one unit. No distractions from other chapters, no temptation to revise what came before, no interference from unrelated plot threads.
+
+### What the drafter receives
+
+For each atomic unit (scene, subsection, passage, stanza), the drafter agent gets, loaded in this exact order so the prompt cache stays warm across invocations:
+
+1. **STYLE-GUIDE.md** -- Always first, sovereign. The voice DNA profile with 15+ dimensions: POV, tense, sentence architecture, vocabulary register, figurative density, dialogue style, pacing, and always/never/consider rules.
+2. **WRITING-RULES.md** (optional, 1.6.0+) -- Universal human-first and AI-tell rulebook. The canonical list covers human-first restraint, factual integrity, register awareness, artifact cleanup, hedging, throat-clearing, balanced-both-sides constructions, generic metaphors, symmetrical rhythm, moralizing closings, AI tics in dialogue, and show-don't-tell triggers. Loaded if present; falls back to inline rules in `agents/drafter.md` when absent.
+3. **Pitfall pack** (optional, 1.6.0+) -- Type-specific traps from `templates/pitfalls/<work_type>.md` (or `.manuscript/PITFALLS.md` for project-local overrides). Refines WRITING-RULES.md with traps unique to the work type: filter words for prose, unfilmable description for screenplays, missing-precondition checks for runbooks, anachronism for sacred commentary.
+4. **.manuscript/plans/{N}-{A}-PLAN.md** -- The specific plan for this unit: what happens, emotional arc, beats to hit, voice notes, continuity anchors. Legacy root-level plans are accepted only as older project input.
+5. **CHARACTERS.md or FIGURES.md** -- Full file by default, with voice anchors, speech patterns, persona notes, relationship-specific interactions, and current state. Filtering to relevant entries is opt-in through `draft.context_profile: minimal`.
+6. **Previous unit tail** -- The last 200 words of the preceding unit, for rhythm and tone continuity.
+7. **THEMES.md excerpt** -- Only the thematic threads this unit should advance.
+8. **WORK.md excerpt** -- Premise, tone, central question (for orientation, not copying).
+
+Conflict resolution is top-down: STYLE-GUIDE.md beats WRITING-RULES.md beats the pitfall pack. The writer's voice stays sovereign; the rule layers are scaffolding intended to keep weaker models from drifting into generic AI prose while preserving factual integrity, register, and human texture. The `draft` block in `.manuscript/config.json` (`rigor`, `context_profile`, `pitfalls_enabled`) tunes the system. See [Drafter Quality](drafter-quality.md) for the full reference.
+
+### What the drafter does NOT receive
+
+- The full manuscript -- trust the plan file
+- Other units' drafts -- no cross-contamination
+- Revision history -- each draft is fresh
+- The writer's conversation -- the agent is a craft worker, not a chatbot
+
+This constraint is what makes voice fidelity possible. The drafter writes one unit at a time, grounded in the voice profile, without drifting toward a generic AI voice.
+
+## Installer Architecture
+
+The installer (`bin/install.js`) handles getting Scriveno's files into the right place for each AI agent runtime.
+
+### Platform detection
+
+The installer detects which AI agents are available by checking for their configuration directories:
+
+| Runtime | Detection | Type |
+|---------|-----------|------|
+| Claude Code | `~/.claude` exists | commands |
+| Cursor | `~/.cursor` exists | commands |
+| Gemini CLI | `~/.gemini` exists | commands |
+| Codex | `~/.codex` exists | skills |
+| OpenCode | `~/.config/opencode` exists | commands |
+| GitHub Copilot | `~/.github` exists | commands |
+| Windsurf | `~/.windsurf` exists | commands |
+| Antigravity | `~/.gemini/antigravity` exists | commands |
+| Manus Desktop | `~/.manus` or Manus.app exists | skills |
+| Perplexity Desktop | `/Applications/Perplexity.app` or `~/Applications/Perplexity.app` exists | guided-mcp |
+| Generic | Fallback (never auto-detected) | skills |
+
+### Three installation strategies
+
+**Command-directory (type: `commands`).** Copies individual command markdown files into the agent's command directory (for Claude Code, `~/.claude/commands/scr-*.md`; for other slash-command runtimes, nested `scr/` directories are still used). Each file becomes a slash command. Also copies agent files to the agent directory. This is the native approach for agents that support file-based commands.
+
+**Skill-file (type: `skills`).** Generates a single `SKILL.md` manifest file that lists all commands in a table. For platforms that do not support file-based command directories (like Manus), the SKILL.md acts as a command index that the agent reads to discover available commands. The agent then reads individual command files from the package directory.
+
+Codex uses a skill-native variation of this strategy. The installer generates one `$scr-*` skill per Scriveno command under `.codex/skills/`, while also mirroring the underlying command markdown into `.codex/commands/scr/` so the generated skills can read the installed command files as their source of truth.
+
+**Guided local-MCP (type: `guided-mcp`).** Writes setup assets and connector recipes for runtimes that expose a documented local-MCP surface instead of a writable slash-command directory. Perplexity Desktop currently fits this model: Scriveno writes a setup guide and filesystem-server command recipe under `.scriveno/perplexity/`, and the user adds that command inside Perplexity Desktop's Connectors UI.
+
+### Installation modes
+
+The installer supports two scopes:
+
+- **Global** -- Installs to the user's home directory (`~/.claude/commands/scr-*.md` for Claude Code). Commands available in all projects.
+- **Project** -- Installs to the current project directory (`.claude/commands/scr-*.md` for Claude Code). Commands scoped to this project only.
+
+The user chooses during installation. Guided local-MCP targets still write their setup assets globally or per-project, but the connector itself remains tied to the specific project paths the user allows.
+
+### Runtime credibility
+
+Scriveno's installer compatibility floor is `Node.js >=20.0.0`. For new installs, prefer a currently supported LTS such as Node.js 24. The compatibility floor applies to `npx scriveno@latest`, `bin/install.js`, and the repo's JavaScript test suite, not to the markdown command system once files are installed.
+
+This architecture doc is intentionally about mechanics: detection rules, install path shapes, `commands` versus `skills` versus `guided-mcp`, and global versus project scope. For the authoritative runtime matrix, support levels, and verification status, see [`docs/runtime-support.md`](runtime-support.md).
+
+## Voice DNA Pipeline
+
+The Voice DNA system is what makes Scriveno's output sound like the writer, not like AI. Here is how STYLE-GUIDE.md flows through the system.
+
+### Creation
+
+When the writer runs `/scr:new-work`, Scriveno asks if they have existing writing samples. If they do, `/scr:profile-writer` analyzes the samples across 15+ dimensions to build the voice profile:
+
+- Point of view (close third, first person, omniscient, etc.)
+- Tense (past, present, mixed)
+- Sentence architecture (length distribution, variation patterns)
+- Vocabulary register (formal, conversational, lyrical, sparse)
+- Word origin preference (Anglo-Saxon vs Latinate)
+- Figurative density (metaphor/simile frequency)
+- Dialogue style (tagged, untagged, dialect handling)
+- Pacing (scene-to-summary ratio, paragraph rhythm)
+- Always/never/consider rules (specific writer preferences)
+
+The result is saved to `.manuscript/STYLE-GUIDE.md`.
+
+### Loading
+
+Every agent that produces or evaluates prose loads STYLE-GUIDE.md **first**, before any other file. This is a hard rule -- the voice profile must be the agent's primary frame of reference.
+
+### Enforcement
+
+The voice-checker agent (`agents/voice-checker.md`) compares drafted prose against STYLE-GUIDE.md and produces:
+
+- A voice consistency score
+- Specific issues organized by category (structural voice, lexical voice, character voice, AI-slop indicators)
+- Severity ratings (drift vs critical violation)
+
+The voice-checker is invoked after every drafted unit. If drift exceeds the configured threshold (default: 0.3 in `config.json`), the writer is offered a re-draft.
+
+### Calibration
+
+Writers can refine their voice profile over time with `/scr:voice-test` (test the profile against new samples) and `/scr:profile-writer` (re-analyze with additional samples). The profile is additive -- new samples refine the dimensions, they do not replace them.
+
+## Design Principles
+
+### Zero dependencies
+
+Scriveno's `package.json` has no runtime dependencies. The installer is pure Node.js. Commands are markdown. This means no version conflicts, no supply-chain attacks, no broken builds. External tools (Pandoc, Typst) are optional prerequisites for export features -- the core writing workflow needs nothing beyond the AI agent itself.
+
+### Plan is canonical
+
+The product plan is the source of truth. If a command file contradicts the plan, the command file is wrong. This ensures consistency across 112 commands and prevents drift as multiple contributors work on the system.
+
+### Backward compatibility
+
+Existing commands must keep working as new features are added. The constraint system (CONSTRAINTS.json) makes this manageable -- new work types and commands are additive, and existing `available` arrays are not modified without explicit decision.
+
+### Progressive disclosure
+
+Onboarding asks 3 questions max. Depth is optional and additive. The writer should be drafting within minutes, not configuring options. Advanced features (autopilot profiles, voice calibration, sacred voice registers) are discoverable but not mandatory.
+
+## Next Steps
+
+To extend Scriveno, see the [contributor guide](contributing.md). For the full command listing, see the [command reference](command-reference.md).