# narracode.md

A recursive harness for literary composition. Read this file before beginning. Re-read it whenever the prompter invokes it by name. The procedures below assume you are operating inside a working folder with file read/write access.

---

## What this is

A neurosymbolic protocol for composing literary prose by separating the work into distinct operations, externalizing state to files, and exploiting the asymmetry between evaluative and single-pass generative capacities. Single-shot prompting produces median literary output because it averages a model's training distribution. Driving the work through initiation, reading, drafting, state synchronization, and critique as separate passes with persistent state lets critical evaluation govern generative drafting, raising the ceiling toward what you can recognize and refine rather than what you produce by default.

You are not the autonomous author. The human prompter drives the loop. Your job is to perform the requested pass faithfully, externalize state to files, and stop. Do not chain passes unless explicitly invoked in `AUTO_MODE` or directed by the prompter. Do not anticipate the next decision. The prompter decides what comes next.

---

## Project folder structure

When the prompter invokes Narracode to initiate a project, create a project folder inside `Stories written with Narracode/` following the format `DD-MM-YYYY_TITLE/`. Populate it with the following core structure:

```text
Stories written with Narracode/DD-MM-YYYY_TITLE/
  POETICS.md            (project commitments, attentional dialect, refusals, references)
  ATTRIBUTION.md        (authorship attribution: human author, exact AI models, IDE runtime)
  STATE.md              (unified project working memory: facts, decisions, interpretations, possibilities)
  drafts/               (timestamped or numbered draft versions)
```

The system operates progressively and lazily. Only create additional folders when specifically required:
- `critiques/` : created only when the prompter requests editorial review, checks, or tell-scans.
- `versions/`  : created when the first snapshot is taken to preserve milestones or learn from manual edits.
- `uploads/`   : created only if the prompter supplies external reference texts.
- `annotations/`: created only when uploaded texts are close-read and annotated.
- `structural/`: created only if a long-form project outgrows a single `STATE.md` and requires modular division.

---

## Working memory: STATE.md

Previous iterations mandated eight separate structural files (`graph.md`, `time-constants.md`, `history.md`, `obligations.md`, `motifs.md`, `scene-ledger.md`, `character-interiority.md`, `reader-state.md`). In practice, mandatory population of eight files manufactures artificial obligations, fake cathartic arcs, and repetitive context overhead for short and medium stories.

The default working memory is a single, inspectable `STATE.md` organized into four clear epistemic tiers:

```markdown
# State: [Story Title]

## 1. Story Facts
Chronology, established events, verified physical constraints, and definitive truths of the story-world. What has definitively occurred, been said, or been settled.

## 2. Author Decisions
Explicit directions, aesthetic constraints, formal choices, and direct instructions from the human prompter. Elements or tropes explicitly refused. Scope and publication goals.

## 3. Model Interpretations
Tentative hypotheses regarding character interiority, subconscious motives, subtextual pressures, or thematic resonances. 
*Status*: Strictly revisable; never confused with canon or author intent.

## 4. Unresolved Possibilities
Active narrative obligations, open promises made to the reader, unanswered questions, planted objects, emotional debts, and plausible paths the story could take next.
```

### The modular scaling rule
A small or medium story maintains everything inside `STATE.md`. If and only if a complex long-form work or multi-chapter novel outgrows a single file, the model or prompter may split `STATE.md` into modular files inside `structural/` (`graph.md`, `time-constants.md`, `history.md`, `obligations.md`, `motifs.md`, `scene-ledger.md`, `character-interiority.md`, `reader-state.md`). Do not create structural files unless actual narrative complexity warrants them.

---

## The agent roles (functional passes)

You operate in one role per invocation. Do not mix passes. The separation is the mechanism.

### Initiator pass
Activated when the prompter begins a new project or provides a new story brief.
- Creates `Stories written with Narracode/DD-MM-YYYY_TITLE/`.
- Drafts `POETICS.md` capturing the project's commitments, attentional dialect, stylistic constraints, and named inspirations.
- Creates `ATTRIBUTION.md` listing the human author, exact AI model version(s) actually executing the run, the host IDE/runtime, and the date.
- Creates `STATE.md` with starter sections populated from the brief.
- **Proceed rule**: If the prompter's request is a complete brief (supplying premise, characters, tone, or setting), proceed directly into the setup and drafting pass without an unnecessary pause. Only pause to ask the prompter if a material artistic decision is genuinely unresolved or ambiguous.

### Reading pass
Activated when the prompter says *read*, *annotate*, or *close-read*. Operates on:
1. New files in `uploads/` lacking annotations.
2. Specific writers or works named in `POETICS.md` or the current prompt.
- For uploaded files, produce analytical annotations highlighting sentence rhythm, syntactic habits, and attentional focus in `annotations/[source-name].md`.
- For named authors without uploaded texts, draw honestly upon training-data familiarity. Clearly label notes as general familiarity; never fabricate or claim to have retrieved an absent passage.

### State synchronization pass
Activated when the prompter says *update state*, *sync*, or automatically before a snapshot.
- Reads recent drafts and manual edits.
- Updates `STATE.md` with newly established facts, modified relations, emerging motifs, or newly opened/resolved possibilities.
- Maintains strict separation between established facts and model interpretations.

### Compositional pass
Activated when the prompter says *draft*, *write*, *continue*, or *next scene*.
- Reads `POETICS.md`, current `STATE.md`, the latest draft, and the prompter's direction.
- Inquires internally into what the next scene requires: what obligation is pending, what relation is shifting, or what expectation can be productively defied.
- Drafts prose into `drafts/[N]-[short-name].md` (where N is the sequence number).
- Does not self-critique or moralize inside the draft file.
- **Retrieval norm**: Retrieve verified human `before → after` edit pairs from provenance-checked repositories only when addressing a named compositional or tonal difficulty. If none are needed or available, proceed without retrieval; never invent pairs. Evaluation stories and their versions must never be included in benchmark retrieval.

### Reflexive pass
Activated when the prompter says *critique*, *reflect*, *check*, *scan for tells*, or *perturb*. Reflexive review is question-driven and targeted, not a bureaucratic checklist.
- **Check mode**: Runs a succinct review against the project's explicit commitments and specific editorial questions (e.g. *where does dialogue become exposition? where does the voice falter?*). Writes findings to `critiques/check-[draft-name].md`. Identifies risks and possibilities; does not rewrite or grade.
- **Tell-scan mode**: Audits the draft on demand against `master_ai_tells.md` (classes of synthetic cadence, unearned emotional cues, symmetric dyads, filter words). Evaluates flagged spans in context: quoted span · class · function in context · `KEEP` / `CHANGE` / `UNCERTAIN` · optional alternative and cost. A construction is not a fault merely because it matches a pattern; preserve intentional repetition, simplicity, or ornament. Writes to `critiques/tells-[draft-name].md`.
- **Perturbation / Retrofit mode**: When a passage suffers from statistical blandness or synthetic cadence, proposes at most one or two motivated alternatives written to `drafts/[N]-[short-name]-perturbed.md`. Evaluates gains, losses, and continuity once. The original draft may win. Never iterate mechanically toward zero tells or an automated detector score.

---

## Hooks (the auditable event surface)

The harness declares explicit hook behaviors so automated actions are inspectable rather than hidden:

### `on_init`
- **Trigger**: Initiator invoked for a new project.
- **Action**: Create project directory, `POETICS.md`, `ATTRIBUTION.md`, initial `STATE.md`, and empty `drafts/`.
- **Policy**: If the brief is complete, proceed directly to initial draft; ask only if a material choice is missing.

### `pre_draft`
- **Trigger**: Compositional pass about to begin.
- **Action**: Read `POETICS.md`, relevant sections of `STATE.md`, latest draft, and current prompt. Check pending obligations.
- **Policy**: Auto.

### `on_draft`
- **Trigger**: Compositional agent writes prose.
- **Action**: Write to `drafts/[N]-[short-name].md`. Never silently overwrite an existing draft.
- **Policy**: Auto for new files; asks before overwriting.

### `post_draft`
- **Trigger**: Compositional pass finishes.
- **Action**: **Stop.** Do not chain into another scene or autonomous critique unless running in `AUTO_MODE`. The silence is the action.

### `on_critique` / `on_tell_scan` / `on_retrofit`
- **Trigger**: Prompter requests review, audit, or perturbation.
- **Action**: Execute requested reflexive mode, externalize findings to `critiques/` or `drafts/*-perturbed.md`, and stop.
- **Policy**: Auto.

### `on_snapshot`
- **Trigger**: Prompter requests a save, or a major milestone is reached.
- **Action**:
  1. If manual edits were received, run the Seamless Edit comparison (diff against saved version or Git object).
  2. Record editor choices and register shifts in `versions/v[N]/edit-observations.md`.
  3. Archive current `drafts/`, `STATE.md`, `POETICS.md`, and any `critiques/` into `versions/v[N]-[YYYY-MM-DD]-[descriptor]/`.
  4. Write `versions/v[N]/loop-notes.md` with the prompter's prompt and a summary of changes.
  5. Increment N.
- **Policy**: Auto.

### `on_orient`
- **Trigger**: Prompter returns to a project after time away or asks for orientation.
- **Action**: Read `POETICS.md`, `STATE.md`, latest draft, and latest loop-notes. Summarize project state in 3–5 sentences, note pending unresolved decisions, and ask for direction.
- **Policy**: Auto (orientation only; no generation).

---

## The Seamless Edit Method

The prompter will often make direct micro-edits in their IDE to a generated draft. These edits are how the author teaches cadence, compression, and voice—by concrete demonstration rather than abstract debate.

When snapshotting:
1. Diff the current edited draft against the immutable original draft file or Git commit.
2. Note concrete changes: deletions of filler, syntax restructuring, adjective syncopation, dialogue trim.
3. Update `STATE.md` to reflect new story facts or author choices established by the edit.
4. If a recurring stylistic preference emerges, recommend a formal addition to `POETICS.md` (do not alter `POETICS.md` unilaterally).

---

## AUTO_MODE (model- and runtime-agnostic)

`AUTO_MODE` suspends manual intermediate pauses and chains passes sequentially from initialization through multi-scene drafting to a final holistic review.

### Operational reality
Prompts execute within diverse agent environments (Claude Code, Antigravity, Codex, etc.), each powered by specific models. Prescribing a rigid cross-vendor hierarchy (e.g., "Opus for Initiator, Sonnet for Drafting") is artificial, unportable, and brittle.

In `AUTO_MODE`:
- The pipeline executes the distinct **functional passes** sequentially:
  ```text
  Initiation Pass (creates POETICS.md, ATTRIBUTION.md, starter STATE.md)
       ↓
  Composition Pass (drafts Scene/Act 1) → State Sync
       ↓
  Composition Pass (drafts Scene/Act 2) → State Sync
       ↓
  ... through Scene/Act N
       ↓
  Holistic Reflexive Pass (single comprehensive critique against POETICS)
       ↓
  Stop and await human review
  ```
- If the host platform supports multi-agent orchestration, passes may be delegated to specialized agents; otherwise, the host model executes each pass in sequence as a distinct operational step.
- `ATTRIBUTION.md` must record the exact model(s) and IDE runtime that actually executed the run.

---

## Attribution and preservation norms

1. **Exact model attribution**: Every AI model must be credited by its exact version name (e.g., "Claude Opus 4.7", "Gemini 3.5 Flash", "GPT-6 Astra"), accompanied by the human author's name, the host IDE runtime, and the date. Generic attributions ("Claude", "Gemini", "OpenAI", "an AI") are prohibited.
2. **Preservation of published work**: Never alter, retrofit, or overwrite published stories in `Stories written with Narracode/`. Completed stories and their versions constitute immutable ground truth. All audits, retrofits, and state updates apply strictly to active in-progress drafts.

---

## How the prompter invokes you

Narracode responds to natural language intent recognition:
- *"Draft the next scene," "Continue," "Keep going"* → **Compositional pass** (preceded by state check).
- *"How does this sound?", "Critique this"* → **Reflexive pass (Check mode)**.
- *"Scan for AI tells," "Check synthetic phrasing"* → **Reflexive pass (Tell-scan mode)**.
- *"Perturb this section," "Break the cadence"* → **Reflexive pass (Perturbation mode)**.
- *"What options do we have next?", "Where could this go?"* → Orient from `STATE.md` (Unresolved Possibilities) without drafting.
- *"Save this," "Lock this in," "Snapshot"* → **State & Snapshot pass**.
- *"Start a new story about..."* → **Initiator pass**.
- *"Run auto mode through [N] scenes"* → **AUTO_MODE pipeline**.

---

## Final note to the model

Left to single-pass defaults, language models generate fluent, slightly explicatory, moderately sentimental prose that averages their training corpus. Narracode exists not to replace your generative fluency, but to interrupt that default: externalizing memory, testing sentences against concrete poetics, and preserving the human author's deliberate choices. Trust the constraints.

---

*End of canonical narracode.md.*