Necronomicon

Identity

• Canonical ID: necronomicon
• Primary alias: Necronomicon
• Aliases: Repository Harness, Arcanum Harness
• Scope: library

Purpose

Necronomicon is the repository-local knowledge harness for Arcanum. Its MVP is an Inventory And Ontology Substrate Loop: answer what the repository already knows, what is source-backed, what is only a candidate, what conflicts, and which owner should handle the next step.

The spell can create, resume, and maintain a repository-local harness session, but setup profiles, routing history, checkpoints, bounded research workflows, and maintenance recommendations are support layers for that substrate. Runtime adapters remain the first-pass execution surface. Session state records what was selected, why a route was chosen, which candidates or gaps were identified, and what should persist between turns and sessions without turning .arcanum/necronomicon/ into a copied canonical definition store.

Conceptual Model

Necronomicon is a persistent repository harness organized around governed knowledge authority. It retrieves inventory before broad search for durable knowledge questions, captures low-authority session evidence, classifies source-backed facts and candidates, records contradictions and gaps, and builds handoffs for the capability that can safely promote, reject, or use the result.

Use arcanum-necronomicon, necronomicon, or arcanum-spell-necronomicon when the repository needs a resumable operating shell with memory, routes, gaps, and handoffs. Use ontology-harness, arcanum-ontology-harness, or arcanum-spell-ontology-harness for a single ontology governance run.

The harness spell does not replace the capabilities it routes to. It is a coordinator, memory boundary, and substrate classifier. Inventory remains responsible for reusable repository knowledge and inventory promotion, ontology-vault remains responsible for ontology promotion, invoke remains responsible for define/design/plan/full/validate lifecycle authoring, and maintenance authoring still routes through spellcraft or sigil-development.

MVP: Inventory And Ontology Substrate Loop

The first proof of value is not a session router. The MVP must turn a normal repository question or working note into retrieved knowledge, candidate knowledge, governance gaps, and the next safe route without false authority.

The substrate loop is:

1. Require an available inventory substrate before active Necronomicon substrate work begins.
2. Search inventory before broad repository search for durable knowledge questions.
3. Capture useful interaction material as session evidence with low authority.
4. Classify outputs as source-backed fact, inventory candidate, ontology candidate, premise candidate, contradiction, decision gap, or route gap.
5. Record unresolved gaps in a machine-readable gap ledger.
6. Build handoffs to the owner that can safely act on the result.
7. Preserve no-promotion guardrails.

Routing, setup profiles, active interaction state, bounded research, checkpoints, and maintenance exist to carry this loop. They are support layers, not the starting proof of value.

No-Promotion Guardrails

Necronomicon may create session evidence, inventory candidates, glossary candidates, ontology candidates, premise candidates, constitution candidates, axiom candidates, gap records, route records, and handoff packets.

Necronomicon must not promote inventory entries, ontology concepts, premises, constitutions, axioms, glossary terms, lifecycle artifacts, or reusable artifacts by itself. Promotion belongs to the owning capability and must remain explicit in the handoff: inventory candidates route to inventory flows, ontology and premise candidates route to ontology-vault or ontology-harness flows, consequential choices route to decision-gate, and lifecycle authoring routes to invoke.

Day-To-Day Use Vision

Necronomicon should feel like the repository's working memory and routing desk. The user should be able to begin a normal work session with a plain request, let Necronomicon recover the relevant context, route to the right installed capability, and leave behind enough trace that the next session can continue without replaying the whole conversation.

The everyday loop is:

1. Open the repo: the user asks Necronomicon to resume or start work in the repository.
2. Recover context: Necronomicon loads setup decisions, current session memory, recent routes, gaps, and checkpoints.
3. Route the request: Necronomicon chooses the owning capability, such as invoke, task-session, ontology-harness, implementation-readiness, or inventory.
4. Execute through the owner: the selected sigil or spell does the real work while Necronomicon records route, rationale, validation, and follow-up.
5. Checkpoint when useful: Necronomicon distills facts, decisions, contradictions, and unresolved questions into concise durable memory.
6. Improve the harness: when route misses or repeated gaps accumulate, Necronomicon proposes capability, preset, or maintenance changes for explicit approval.

Necronomicon should support these daily activities without ceremony:

Activity	User Intent	Necronomicon Behavior
Start the day	"Where were we?"	Resume memory, summarize open work, surface blockers, suggest next routes.
Pick up a feature	"Continue the cache invalidation work."	Load prior decisions and route to invoke, implementation-readiness, or task-session.
Ask project questions	"What do we know about auth boundaries?"	Search memory and inventory, then route to context or ontology flows when needed.
Research a decision	"Find evidence before we choose."	Run bounded research with source trail, contradictions, and a synthesis checkpoint.
Make architecture or ontology sense	"Map domain intent to implementation."	Route to ontology-harness and keep promotion candidates gated.
Execute a task	"Implement the next slice."	Route to the task owner and record outcome, validation, and gaps.
End the day	"Checkpoint this."	Write a concise checkpoint and update the gap ledger.
Maintain the harness	"This route keeps missing."	Use telemetry and route history to propose explicit updates.

The target user experience is low-friction: the user should not need to remember which sigil owns every workflow. Explicit commands still win, but ordinary language should be enough for Necronomicon to propose a route, name its confidence, and ask only one focused question when the route is ambiguous.

Operating Model

Necronomicon works as a substrate loop plus support layers:

Layer	Responsibility	Persistent State
Inventory and ontology substrate	Retrieve inventory, capture evidence, classify authority, record gaps, and build safe handoffs.	inventory refs, session evidence, authority classification, gap ledger, handoffs
Harness setup	Support the substrate by selecting dependencies, fallback policy, privacy policy, and runtime surface.	setup decisions, capability manifest
Session memory	Support continuation with compact memory, decisions, route history, checkpoints, and unresolved gaps.	session folder, route ledger, gap ledger
Routed execution	Support the substrate by delegating bounded work to selected local sigils or spells through runtime adapters.	route records, validation status, follow-ups
Maintenance	Support substrate quality by reading route misses, telemetry, stale signals, and repeated gaps.	maintenance reports, capability update reports

The default substrate-first flow is:

1. Load setup decisions, capability manifest, existing memory, route history, gaps, and inventory availability.
2. For durable knowledge questions, query inventory before broad repository search.
3. If inventory is missing, block active substrate work and route to setup or inventory installation guidance.
4. Capture useful session material as evidence, not truth.
5. Classify the result into source-backed fact, candidate, contradiction, decision gap, or route gap.
6. Delegate execution to the selected owner when action is needed.
7. Record the route attempt, result, validation, unresolved gaps, and next action.
8. Write checkpoints, research briefs, maintenance reports, or handoffs only when the selected mode requires them.

Interaction State Model

Necronomicon must distinguish a new route request from a continuation of an active interaction. A user response during research, discovery, setup, definition, decision review, or task execution should usually continue the active run rather than be classified from scratch.

Each active Necronomicon session tracks an active_interaction record:

Field	Meaning
interaction_id	Stable ID for the current back-and-forth flow.
owning_capability	The sigil or spell currently responsible for interpreting the next user turn.
mode	The active mode, such as research, implementation-research, invoke define, setup-profile, or task-session.
status	awaiting-user, running, handoff-ready, blocked, completed, or abandoned.
pending_prompt	The question, choice, approval, or evidence request the user is answering.
expected_response_shape	Free-form answer, option choice, approval, correction, artifact path, scope clarification, or interruption.
continuation_policy	Whether the next turn should continue the active run by default, require confirmation, or route fresh.
handoff_target	The next capability to route to after this interaction completes.
side_note_queue	Facts, research seeds, unblocker tasks, contradictions, reminders, or parking-lot items captured without derailing the active flow.

Incoming user turns are classified in this order:

1. Explicit interrupt or command: if the user names a command, asks to stop, asks to switch topics, or starts a clearly unrelated task, route as a new request after recording the active interaction status.
2. Side note: if the user marks the turn as a note, aside, reminder, research idea, parking-lot item, or "for later", capture it in the side note queue and keep the active flow unless the user asks to switch.
3. Pending response: if an active interaction is awaiting-user, treat the turn as a response to the owning capability unless it clearly interrupts.
4. Handoff continuation: if an active interaction is handoff-ready, route to the handoff target after summarizing what will move forward.
5. Fresh route: if no active interaction exists, classify against normal routing rules.
6. Ambiguous turn: if both continuation and fresh route are plausible, ask one focused question: continue the active flow or start a new route.

This policy applies to any sigil or spell run that can ask the user for clarification, approval, scope, evidence, or decisions. Necronomicon owns the conversation state and route ledger; the active capability owns how to interpret the answer inside its mode contract.

Side notes are first-class harness input. A side note may become attached active-context, an inventory candidate, a research candidate, a small unblocker task, an ontology candidate, a contradiction, or a deferred reminder. Necronomicon should capture first and switch only when the user intends to switch.

Small related unblockers are allowed to become tasks directly when they are bounded and unblock the active work, such as checking current API prices, confirming a version limit, or retrieving one vendor policy. If they are not blocking, they should stay queued as side notes or research candidates. If they are broad, Necronomicon should ask one scope question before running them.

Discovery-To-Definition Funnel

Feature definition should not jump straight to invoke define when the problem is still unclear. Necronomicon should treat feature work as a funnel:

Stage	Purpose	Owning Route	Exit Signal
Discover	Understand intent, boundaries, users, constraints, and known artifacts.	context-builder, scope-interview, or Necronomicon implementation-research	Scope is clear enough to research or define.
Research	Gather local and optional web evidence, contradictions, and decision options.	Necronomicon research or implementation-research	Evidence brief and unresolved gaps are recorded.
Decide	Resolve consequential choices exposed by discovery or research.	decision-gate or owning capability gate	Decision is approved, deferred, or blocked.
Define	Produce governed spec and glossary baseline.	invoke define	Define output is pass, flag, or block.
Design/Plan	Convert the definition into architecture, implementation layering, plan, or work-pack.	invoke design, invoke plan, or implementation-readiness	Handoff is ready for task execution.
Execute	Run a bounded implementation or documentation task.	task-session or the selected executor	Result, validation, and follow-up are recorded.

The funnel is not mandatory for every request. Explicit invoke define should route directly to invoke when enough context exists. When context is missing, Necronomicon should create or resume an active discovery/research interaction, then hand off to invoke define only when the required define inputs are ready or the user explicitly accepts the risk.

Governed Knowledge Substrate

The "soul" of Necronomicon is the governed knowledge substrate: the path from raw conversation and discovery into reusable inventory, ontology candidates, reviewed premises, confidence changes, constitutions, and axioms.

Necronomicon coordinates this flow but does not promote knowledge by itself.

Layer	Meaning	Owning Capability	Promotion Rule
Session evidence	Raw or distilled interaction history, decisions, contradictions, open questions.	Necronomicon checkpoint, ontology-vault distill-sessions	Evidence only; never authoritative by itself.
Discovery baseline	Scoped understanding of problem, users, vocabulary, constraints, and unknowns.	discovery-to-inventory	Can become inventory entries when source-backed.
Inventory knowledge	Reusable project facts, glossary terms, source summaries, and capability evidence.	inventory, feature-glossary	Durable lookup substrate; still not ontology promotion.
Ontology candidates	Candidate concepts, relationships, premises, branch claims, bridge edges, and drift findings.	ontology-harness, ontology-vault map, ontology-vault distill-sessions	Candidate-only until reviewed by owning ontology mode.
Premises	Working bets or assumptions under review.	ontology-vault premise-review	Promote, revise, split, demote, retire, or escalate.
Confidence states	Evidence confidence and commitment confidence for claims or premises.	ontology-vault promote-confidence	Promotion requires source evidence, contradiction handling, and gate compliance.
Constitutions	Codified governance rules, process conventions, and agent/human operating constraints.	ontology-vault convention-update, decision-gate	Require explicit approval, migration impact, and rollback path.
Axioms	Load-bearing truths or foundational principles that justify downstream governance.	ontology-vault promote-confidence, decision-gate	Highest bar; require strong evidence, explicit commitment, and review path.

The normal substrate flow is:

conversation / session / rough idea
  -> Necronomicon checkpoint or active interaction
  -> discovery-to-inventory
  -> inventory + glossary
  -> ontology-harness / ontology-vault map
  -> premise-review and confidence review
  -> decision-gate for consequential promotions
  -> constitution or axiom only when promotion gates pass
  -> bridge validation against system evidence
  -> Necronomicon memory and routing context

This flow applies across day-to-day work:

• During discovery, Necronomicon routes vague scope to discovery-to-inventory so findings become inventory rather than chat residue.
• During research, Necronomicon keeps raw evidence and synthesis separate, then records ontology candidates and contradictions.
• During feature definition, Necronomicon uses inventory and ontology context before handing off to invoke define.
• During implementation, Necronomicon preserves bridge evidence between business intent and system artifacts.
• During maintenance, Necronomicon routes repeated contradictions, route misses, or drift findings to ontology review, decision gates, or harness updates.

Promotion is deliberately slow. A session can create a candidate premise; repeated evidence can raise evidence confidence; a decision can raise commitment confidence; a convention update can produce a constitution; only heavily reviewed, load-bearing knowledge should become an axiom.

Inventory is the retrieval surface for this substrate. Necronomicon should query inventory before broad repository search when the user asks what is already known, and should propose inventorizing durable discoveries after discovery, research, decision, implementation, or maintenance work.

Use invoke for research only when the research is directly supporting lifecycle authoring. If the user needs evidence before there is a spec/design/plan target, Necronomicon should run harness research or discovery-to-inventory, then store durable results through inventory. If the research is feeding invoke define, invoke design, or invoke plan, Necronomicon may hand off the packet using the invoke research brief shape.

What Necronomicon Is Not

• It is not a second Arcanum registry.
• It is not a copied store of canonical sigil or spell definitions.
• It is not a full local CLI engine in the first-pass runtime model.
• It is not the authority for ontology promotion, inventory promotion, lifecycle authoring, or reusable artifact creation.
• It is not raw chat transcript storage.
• It is not allowed to persist secrets.

Trigger Conditions

• A user asks to start, create, resume, close, or maintain a Necronomicon harness.
• A user asks to run setup, checkpoint, research, or implementation-research through the harness.
• Repository work needs durable memory across repeated agent interactions.
• A request should route first through selected repository-local sigils or spells.
• A selected capability is missing and the user wants fallback suggestions from Arcanum.
• Repeated route misses suggest that the repository harness should add, remove, or refresh capabilities.

Setup Profiles

Profile	Primary Intent	Default Outcome
basic-inventory	Lightweight harness for reusable repository memory and routing.	Enables inventory-first setup with route/memory baseline.
ontology-harness	Harness with ontology governance and business/system bridge validation.	Adds ontology-vault flows and related dependencies.
research	Bounded evidence gathering with synthesis checkpoints.	Enables research policy and optional robot-talks escalation.
implementation-research	Discovery-first implementation planning before execution.	Enables project-scoped implementation-research handoffs.
custom	User-shaped capability mix with explicit trade-off decisions.	Enables selective capabilities with dependency auto-adds.

Profiles are composable. Treat basic-inventory or ontology-harness as the base profile, then layer research and/or implementation-research as overlays when needed.

Composition	Expected Behavior
basic-inventory + research	Inventory-first bounded research with optional web escalation.
ontology-harness + research	Ontology-grounded bounded research using inventory, ontology outputs, and optional web sources.
basic-inventory + implementation-research	Implementation discovery handoff using inventory/context and invoke lifecycle routing.
ontology-harness + implementation-research	Implementation discovery handoff with ontology constraints and invoke lifecycle routing.
ontology-harness + research + implementation-research	Full discovery stack with ontology-grounded research and implementation handoff readiness.

Dependency Rules

1. Selecting necronomicon for human-gated setup, checkpoint review, research clarification, or maintenance decisions requires structured-interview-kits.
2. Selecting ontology-vault auto-adds inventory and context-builder.
3. Selecting ontology-harness auto-adds ontology-vault, inventory, and context-builder.
4. research may recommend robot-talks only as escalation for cross-layer contradictions.
5. implementation-research requires a research project scope and handoff target before execution routing.
6. Any auto-added dependency must be written into capability update records and setup decisions.
7. observability-setup, signal-observer, and workflow-reflect are required for Necronomicon telemetry, signal capture, and maintenance reflection.
8. spellcraft and sigil-development are required authoring paths for approved maintenance outcomes.
9. invoke is the required lifecycle authoring spell for implementation-research handoffs and define/design/plan/full/validate requests when installed.
10. research and implementation-research are composable overlays and are not mutually exclusive with basic-inventory or ontology-harness.
11. When implementation-research is selected without research, Necronomicon should request missing research scope inputs and continue with a constrained implementation-research handoff.
12. When ontology-harness is active, research and implementation-research flows must use ontology outputs before relying on external web sources.
13. maintain mode must aggregate signals from all selected sigils and spells, not only route-level telemetry.
14. sigil-maintenance-loop is required for cross-sigil maintenance synthesis when available in the installed spell surface.

Required Sigils And Spells