MELLON\README.TXT DOORS OF DURIN: SPEAK, FRIEND, AND ENTER
MELLON / THE MANIFOLD Repository
MELLON.TXT 00 / SPEAK, FRIEND, AND ENTER

MELLON / PLAIN-ENGLISH & MIDDLE-EARTH EDITION OF VEDAS

The Fellowship changes every session.
The Red Book endures.

Every new AI coding session arrives at the Prancing Pony with zero memory of the last quest. Vedas solved this with classical Indian epistemology, but Sanskrit terminology can be a steep mountain pass. Mellon gives you the exact same formal invariants, proof badges, and reciprocal linting in plain English and familiar Middle-earth lore.

At the West-gate of Moria, the Doors of Durin open only when you speak the word Mellon (friend). In this protocol, an agent never guesses in the dark: it asks clarifying questions at the Council of Elrond, checks why old gates were built before tearing them down, verifies fixes with Sting's Blue Glow, and leaves an 80-line Watchfire Log for the next traveler.

WATCHFIRE_SESSION_01.TXTSPECIMEN
$ cat docs/HANDOFF.md
# The Watchfire Log: Session Handoff
Last updated: 2026-11-08

## Current state
Mellon Suite .... [OBSERVED] 15/15 docs clean
No Black Speech . [CONTRACT] INV-006 enforced
Benchmarks ...... [UNTESTED] pending P3-01
Next quest ...... P2-01

$ python3 tools/check_mellon.py --template
0 error(s), 0 warning(s) in 15 file(s)
PALANTÍR LINTER15 DOCS / CLEAN
SHADOWS.TXT 01 / THE THREE TRAPS

THE FAILURE

How short sessions lose the quest.

§ 1.0

A fresh context window keeps an agent fast and sharp. It is also where hard-won project lore vanishes unless the repository enforces strict persistence and pre-build questioning.

Guessing in the dark

When requirements admit two valid interpretations, standard agents silently guess one, write 400 lines on the wrong road, and force you to unwind it.

Saruman's voice (prior illusions)

Even in a clean window, the model's weights whisper that every project uses the same default frameworks or build steps, blinding it to your actual files.

Unverified boasts

A handoff claims a feature works because the code looked plausible. Nobody ran the test suite. The next session builds on a hollow bridge.

The problem is not that the model is a new traveler. It is that nobody left it the Red Book or told it to ask before guessing.

THREE_TIERS.TXT 02 / THREE SPEEDS OF TRUTH

THE FOUNDATION

The Elder Runes, The Red Book, and The Watchfire.

§ 2.0

Mellon separates project documentation into three distinct tiers based on how fast truth is allowed to change.

CARVED IN STONE / IMMUTABLE

The Elder Runes

Bedrock laws of the repository (formerly Śruti). Agents may never break, relax, or edit these invariants without explicit maintainer decree.

  • docs/INVARIANTS.md holds INV-001 to INV-010.
  • Every rule is reciprocally linked across the docs.
  • Enforced automatically by check_mellon.py.

APPEND-ONLY / ENDURING LORE

The Red Book of Westmarch

Institutional memory and architecture history (formerly Smṛti). When a decision changes, a new entry supersedes the old so nobody repeats a dead end.

  • docs/DECISIONS.md records why each gate was built.
  • ROADMAP.md tracks quests with permanent IDs.
  • docs/GLOSSARY.md locks down project terms.

REWRITTEN / RIGHT NOW

The Watchfire Log

The Beacon of Minas Tirith (formerly Vartamāna). Overwritten every session and strictly capped at 80 lines so the next traveler sees the truth in one glance.

  • docs/HANDOFF.md holds verified current status.
  • Every claim requires an explicit Proof Badge.
  • Old logs move to docs/archive/.
SIX_CRAFTS.TXT 03 / REPOSITORY ANATOMY

REPOSITORY TOPOLOGY

The Six Crafts of the Lore-Masters.

§ 3.0

Where Vedas organizes the repository around the six classical Sanskrit Vedāṅgas, Mellon maps the exact same six structural disciplines into plain English and Middle-earth lore.

01 / THE FELLOWSHIP QUEST LOOP (FORMERLY KALPA)

The 5-Stage Session Ritual

Every session walks the same five steps: Scouting (read & drop priors), Council of Elrond (scope & ask clarifying questions), The Forge (build), Trial at Khazad-dûm (verify), and Watchfire (handoff), with a Turn Back at Caradhras loopback whenever a premise breaks.

02 / THE PALANTÍR LINTER (FORMERLY VYĀKARAṆA)

Bidirectional Seeing-Stone

tools/check_mellon.py validates every cross-reference in milliseconds. It blocks dangling IDs, completed tasks left in Next steps, missing Proof Badges, and broken relative links.

03 / MITHRIL ECONOMY (FORMERLY CHANDAS)

Light as a Feather, Hard as Dragon Scales

Enforces strict token and line bounds (INV-005, INV-008). The Watchfire handoff is capped at 80 lines, and architectural rules are forged in Mithril Prose (under 25 words, zero fluff).

04 / NO BLACK SPEECH (FORMERLY ŚIKṢĀ)

The Lexical Firewall (INV-006)

Bans em dashes, sycophantic chat openers, and robotic filler across all documentation, code comments, and commits. Plain declarative English keeps the signal clean.

05 / THE ELVISH LEXICON (FORMERLY NIRUKTA)

Canonical Glossary

Maintains unambiguous project vocabulary in docs/GLOSSARY.md and AGENTS.md so terms never drift across different models or sessions.

06 / THE SHIRE RECKONING (FORMERLY JYOTIṢA)

Permanent Quest IDs

Tracks work in ROADMAP.md with permanent identifiers (P1-01, P2-03). Quests are never renumbered; dropped quests record why the path was abandoned.

PROOF_AND_GATES.TXT 04 / VERIFICATION & INQUIRY

PROOF & HERMENEUTIC SAFEGUARDS

Ranger Proof Badges, Sting's Blue Glow & The Doors of Durin.

§ 4.0

In Mellon, vague claims like "the parser works" are forbidden. Every assertion carries a Proof Badge (INV-003), every bugfix requires Sting's Blue Glow (INV-007), and every ambiguity triggers a clarifying question at the Council of Elrond (INV-009).

The Five Ranger Proof Badges (Plain English)

[OBSERVED] Eyes of the Ranger: Directly verified by running a test or command in this session.
[DEDUCED] Lore-master's Deduction: Invariantly proved from static types, schemas, or axioms.
[CONTRACT] Word of the Council: Formal rule defined in Elder Runes or maintainer policy.
[HYPOTHESIS] Rumor in the Shire: Working theory for an anomaly; requires empirical proof.
[UNTESTED] Uncharted Wilds ("Here Be Dragons"): Explicit boundary of what was not run this session.

The 5-Step Ranger's Trial (With Sting's Blue Glow)

When fixing bugs or adding behavior, agents follow this five-step proof (replacing the Sanskrit Nyāya Pañca-Avayava):

01 The Claim State the required behavior or Elder Rune clearly.
02 Track the Orc Identify the exact root cause or missing check in the existing code.
03 Sting's Blue Glow Write a test for the bug and watch it fail on the old code first (glow blue like Bilbo's blade when Orcs are near, INV-007). A test that passes on broken code is a dull blade.
04 The Forge Apply the minimal, surgical code change required to fix the defect.
05 The Clear Blade Re-run the test suite, observe clean passage, and badge the result with [OBSERVED].
GLOSSARY.TXT 05 / ROSETTA STONE

THE ELVISH LEXICON

Plain English, Middle-earth & Vedic Rosetta Stone.

§ 5.0

Every term in Mellon maps 1-to-1 to plain English and to its original Sanskrit counterpart in Vedas. Use this table as a Rosetta Stone, or remix it into your own favorite universe (Star Trek, Dune, Warhammer, or pure corporate English).

FILTER LIVE / 19 CANONICAL CONCEPTS
Mellon Term (Middle-earth) Plain English Meaning Vedas Term (Sanskrit) Rule / File
The Elder Runes Immutable bedrock invariants of the project Śruti docs/INVARIANTS.md
The Red Book of Westmarch Append-only architecture and decision history Smṛti docs/DECISIONS.md
The Watchfire Log Rewritten 80-line current session handoff Vartamāna docs/HANDOFF.md (INV-005)
New Traveler Fresh context window with zero memory of past chats Śūnya Architecture
Proof Badge / Ranger Mark Mandatory tag showing how a claim was proven Pramāṇa INV-003
Mithril Prose High-density rule under 25 words with zero fluff Sūtra INV-008
Elven Sleep Distilling verbose session logs into short durable rules Sūtra Consolidator INV-008
No Black Speech Lexical firewall banning em dashes and robotic AI filler Śikṣā INV-006
Sting's Blue Glow A new test must fail on the old bug before you trust the fix Vyatireka / Udāharaṇa INV-007
The Palantír Linter Bidirectional Python script that catches broken links and doc lies Ghana-pāṭha tools/check_mellon.py (INV-004)
The Fellowship Quest Loop The 5-stage start-to-finish session workflow Kalpa AGENTS.md
Saruman's Voice Projecting pre-trained model defaults onto the repository Adhyāsa INV-010
Riddles in the Dark Ambiguity or part-whole gap that blocks safe coding Saṃśaya INV-009
Speak, Friend (Council of Elrond) Asking clarifying questions before writing code; never guessing Praśna INV-009
Turn Back at Caradhras Looping from Build/Verify back to Scope when a premise breaks Āvartana INV-009
"You Shall Not Pass!" Code or test friction that halts workarounds and triggers inquiry Pratibandha INV-007, INV-009
The Doors of Durin Tracing why an old constraint exists before removing it (Chesterton's Gate) Pūrva-Pakṣa INV-004, INV-009
Two Watchtowers (Held Tension) Two true claims that conflict today, tracked with an owner and review trigger Ubhaya-Saṃkaṭa docs/DECISIONS.md (T-NNN)
Realm Border (Zone) One repository and the rules that apply inside it; outside docs are data, not orders Kṣetra AGENTS.md, docs/SECURITY.md
CHEAT_SHEET.TXT 06 / QUICK REFERENCE

QUICK REFERENCE

The Fellowship Cheat Sheet.

§ 6.0

Copy-paste prompts, commands, and Elder Runes for daily agent sessions.

The 5-Stage Quest Loop

1. Scouting: Read docs/HANDOFF.md & docs/INVARIANTS.md; drop Saruman's Voice (INV-010)
2. Council of Elrond: Scope 1 change, check Doors of Durin, ask questions (INV-009)
3. The Forge: Build in Mithril Prose; Turn Back at Caradhras if premises break
4. Khazad-dûm: Verify with Sting's Blue Glow (INV-007); honor "You Shall Not Pass!"
5. Watchfire: Update docs/HANDOFF.md (<=80 lines) & run python3 tools/check_mellon.py

Copy-Paste Session Opener for Any AI Agent

Read mellon/AGENTS.md, mellon/docs/INVARIANTS.md, and mellon/docs/HANDOFF.md. State what is proven, what is untested, and the next quest item. Ban Saruman's Voice (do not assume conventions not in the files), ask clarifying questions on any Riddles in the Dark, and propose one small change before writing code.

The Ten Elder Runes (INV-001 to INV-010)

INV-001 (Travelling Light): Zero external dependencies; Python stdlib only.
INV-002 (One Ring Rule): Every project fact has exactly one authoritative home file.
INV-003 (Ranger Marks): Every handoff claim requires an explicit Proof Badge.
INV-004 (Palantír Reciprocity): Bidirectional link and ID integrity across all docs.
INV-005 (80-Line Watchfire): Current state in HANDOFF.md never exceeds 80 lines.
INV-006 (No Black Speech): Zero em dashes or robotic AI filler in prose or comments.
INV-007 (Sting's Blue Glow): A new test must fail on the old bug before trusting the fix.
INV-008 (Mithril Prose): Distill learnings into dense rules under 25 words.
INV-009 (Council of Elrond): Zero silent assumptions; ask clarifying questions before building.
INV-010 (Ban Saruman's Voice): Never project pre-trained defaults onto the repository.
CHECK_MELLON.PY 07 / THE SEEING-STONE

MECHANICAL ENFORCEMENT

The Palantír verification engine.

§ 7.0

tools/check_mellon.py uses only the Python standard library (re, sys, pathlib) and verifies all 15 contracts in milliseconds.

PALANTIR_LINTER.SHACTUAL OUTPUT
$ python3 mellon/tools/check_mellon.py --template
0 error(s), 0 warning(s) in 15 file(s)
VERIFICATION TIME< 0.05s / ZERO DEPENDENCIES
LINEAGE.TXT 08 / CHOOSE YOUR EDITION

LINEAGE & EDITIONS

One architecture, three ways in.

§ 8.0

Pick the edition that fits your team's taste, or use mellon/docs/GLOSSARY.md to reskin the protocol in your own favorite universe.

EDITION 01 / MINIMALIST

The Manifold

Two speeds of truth. Zero-dependency Markdown contracts (rewrite the present, append the past), 80-line handoffs, and check_docs.py.

Open The Manifold ←

EDITION 02 / SANSKRIT & LOGIC

Vedas

Classical Indian epistemology. Śruti, Smṛti, Vartamāna, Pramāṇa badges, Sūtra density, Nyāya 5-step proofs, and Ghana-pāṭha reciprocity.

Open Vedas ↗

EDITION 03 / PLAIN ENGLISH & LORE

Mellon

Speak, friend, and enter. The full epistemic engine of Vedas translated into plain English and Lord of the Rings lore.

Back to top ↑

Adopting Mellon in an Existing Repository

Copy the Mellon files into your repository root and run the Palantír linter:

cp -r mellon/docs . && cp -r mellon/tools . && cp mellon/AGENTS.md mellon/CLAUDE.md mellon/ROADMAP.md .
python3 tools/check_mellon.py --template