holonovel: Instructions file for Codex

AGENTS.md

Project overview

This repository holds the Holonovel specification — a self-contained build specification for a narrative simulation engine whose reference adapter is an MCP server that serves tabletop RPG rulesets from Markdown sources. The canonical document is holonovel.md. This is a specification document, not an implementation.

Spec Kit phased model

The specification follows the Spec Kit phased-artifact model: constitution (§4 Standing Rules), specify (spec/ sources), plan and tasks (per-increment artifacts under plans/), implement (§6 Build Process), and converge (§6.5/§6.7). The house executable-spec conventions (gates, traceability, golden transcript) are the quality checklist layer.

Layer map

holonovel.md             Assembled specification (generated from spec/, committed)
spec/                    Source files — edit here, not holonovel.md directly
  ├── 01-foundations.md  Reading guide, mission, failure modes
  ├── 01a-constitution.md §4 standing rules and terminology
  ├── 02-requirements.md §5 requirements (the normative core)
  ├── 03-build.md        §6 build process (includes Prepare: phase-loading hints)
  ├── 04-runtime.md      §7 runtime conventions
  ├── 05-verification.md §8 verification workflows
  ├── 06-artifacts.md    §9 artifacts and handoff
  ├── 07-independent.md  §10 independent verification
  ├── 08-synthesis.md    §11 optional workflows (Synthesis)
  ├── appendices-reference.md  # Appendices heading + A, D–S, T (reference material)
  ├── appendices-fixtures.md   B, C, N, W–Z (golden, injection, complex, world, social fixtures)
  ├── appendices-licenses.md   U (content licenses)
  ├── appendices-runbooks.md   V (workflow runbooks)
  └── build-phase-map.md Build-phase-to-file dependency table (per-phase loading)

File numbering follows canonical load order, not section number (e.g., 03-build.md = third file loaded, contains §6). README.md Project orientation; see HTML comment at top for README design conventions docs/engine-contract.md Non-normative engine contract (state authority, turns, determinism, event stream, save format, adapter seam) CHANGELOG.md Revision history (date-headed, bulleted) AGENTS.md This file — AI maintainer orientation package.json Task runner (lint, validate, typecheck) .markdownlint.json Lint rules (120-char prose, ATX headings) tsconfig.json TypeScript configuration scripts/validate.ts Cross-reference checker with --traceability flag (REQ citations, test IDs, TOC sync, heading separators, block shape, traceability matrix, coverage completeness, phase-map consistency; REQ-family _Check: coverage; REQ-body content scan; ambiguity and assumption audits merged here) scripts/fmea.ts REQ-level failure mode and effects skeleton scripts/graph-deps.ts REQ dependency graph (DOT/Graphviz output) scripts/lib/parse-spec.ts Shared parsers (readSpec, extractReqBodies, extractReqHeaders) scripts/lib/parse-readme.ts README structural parsers (headings, links, blockquotes) scripts/lib/hash.ts Shared SHA-256 helpers (sha256, hashFile) scripts/lib/walk.ts Shared recursive file walker (walkFiles, walkTsFiles) scripts/lib/similarity.ts Shared tokenize + Jaccard for near-duplicate checks scripts/lib/script-discipline.ts Pure script-discipline detectors (contentIssues, shellIssues) scripts/lib/script-quality.ts Pure script-quality detectors (duplicate helpers, REQ-header predicate) scripts/lib/phase-map-hash.ts Build-phase-map content hash (REQ-278) scripts/check-script-quality.ts Script quality gate: reachability (C1) plus duplicate-helper (C2), repeated-parse (C3), and parser-bypass (C4) — all gated scripts/test-script-tooling.ts Self-tests for the discipline and quality detectors