The unrecorded invariant
Session two reintroduces a naive pattern because session one only discussed the restriction in chat. The code compiles, but the system architecture degrades.
VEDAS / EPISTEMIC EXTENSION OF THE MANIFOLD
Ancient Vedic thinkers faced the exact problem modern autonomous coding agents face: preserving complex, high-dimensional systemic truth across successive generations of ephemeral, amnesiac participants without semantic drift, hallucination, or bit rot.
The Manifold offloaded project state into reproducible text so the model just has to check. Vedas gives that memory an epistemology. By separating truth into three speeds (Śruti invariants, Smṛti history, and Vartamāna temporal handoffs) and requiring rigorous Pramāṇa proof tags for every claim, Vedas guarantees zero drift across sessions. Every fact has a test, a receipt, and an immutable history.
$ cat docs/HANDOFF.md # Session Handoff Last updated: 2026-11-04 ## Current state Tokenizer ....... [OBSERVED] 119/119 pass Grammar ......... [CONTRACT] INV-006 enforced Speech .......... [HYPOTHESIS] pending audio Next task ....... P3-02 $ python3 tools/check_vedas.py --template 0 error(s), 0 warning(s) in 14 file(s) $
THE FAILURE
A fresh context window provides speed and focus. It is also where institutional knowledge vanishes. When an AI session ends, its rationale disappears unless the repository enforces strict epistemic persistence.
Session two reintroduces a naive pattern because session one only discussed the restriction in chat. The code compiles, but the system architecture degrades.
A handoff claims a subsystem works because the author assumes it does. Nobody ran the test command. The next session builds atop unverified speculation.
Without hard lexical and behavioral firewalls, models lapse into predictable, repetitive pleasantries and stock empathy clichés, diluting focus and token budgets.
The problem is not that AI models hallucinate. It is that standard repositories permit unverified claims to pose as ground truth.
THE FOUNDATION
In traditional software development, documentation is treated as a uniform pile of text. Vedas separates repository truth into three distinct temporal tiers, each governed by strict mutability rules.
IMMUTABLE / ETERNAL
The bedrock laws of physics for the project. These invariants cannot be violated, relaxed, or edited without explicit maintainer consent.
docs/INVARIANTS.md houses core rules (INV-001 to INV-010).APPEND-ONLY / EPOCHAL
Institutional memory and historical precedent. Past decisions are superseded rather than erased, showing why dead ends were rejected.
docs/DECISIONS.md stores architectural decisions.ROADMAP.md assigns stable, permanent task identifiers.docs/CHANGELOG.md captures user-facing evolution.REWRITE / LIVING PRESENT
The immediate present moment. Stale claims are deleted immediately. The file is capped at 80 lines and overwritten every session.
docs/HANDOFF.md records verified current status.REPOSITORY ANATOMY
Just as classical scholars maintained oral texts without textual decay for millennia through six specialized disciplines, Vedas organizes repository architecture across six auxiliary limbs.
Enforces strict stylistic hygiene across all documentation and comments. Bans generic stock empathy, chat filler, and typographical quirks like em dashes to maintain crisp, machine-verifiable prose.
Imposes strict structural bounds. Session handoffs are strictly capped at 80 lines, and core architectural propositions (Sūtras) must not exceed 25 words. Brevity preserves cognitive bandwidth.
Mechanically guarantees repository integrity through tools/check_vedas.py. Validates invariant reciprocity, verifies cross-references, and blocks malformed handoffs before commit.
Maintains unambiguous domain vocabulary in docs/GLOSSARY.md. Defines canonical terms, their historical counterparts, and nearby traps to avoid semantic drift between sessions.
Tracks roadmap execution with immutable identifiers (e.g. P1-01, P2-04). Tasks are never renumbered or repurposed. Abandoned tasks record what was learned.
The standard operating procedure executed on every session entry and exit. Governs orientation, verification, surgical changes, validation, and handoff compilation, with spiral Āvartana loopback when a local part reshapes the whole.
EPISTEMIC VERIFICATION
In Vedas, vague assertions like "the exporter works" are prohibited. Every claim must carry a Pramāṇa badge indicating its exact source of epistemic authority.
When resolving defects or adding features, agents follow the classical Nyāya five-part syllogism to guarantee reproducible changes:
PHONETIC GUIDE
Vedas uses classical Sanskrit terminology to provide precise epistemic distinctions. Use the interactive pronunciation guide below to master each term. Click the audio buttons to hear native synthesized speech.
| Term | Phonetic Guide | Audio | Plain English Meaning | Software Equivalent |
|---|---|---|---|---|
| Śruti | SHROO-tee | That which is heard; revealed immutable truth | Immutable invariants (INV-001 to INV-010) | |
| Smṛti | SMRIH-tee | That which is remembered; historical recollection | Append-only ADRs and architecture memory | |
| Vartamāna | var-tuh-MAH-nuh | The immediate living present moment | Session handoff (docs/HANDOFF.md, 80-line cap) | |
| Pramāṇa | pruh-MAH-nuh | Valid means of knowledge or legitimate proof | Epistemic proof tags ([OBSERVED], [DEDUCED]) | |
| Pratyakṣa | pruh-tyuhk-SHUH | Direct perception and empirical observation | Direct test output and telemetry telemetry | |
| Anumāna | uh-noo-MAH-nuh | Inference based on causal deduction | Static analysis and logical deduction | |
| Sūtra | SOO-truh | Aphorism; high-density, minimal-syllable rule | Dense propositional invariant (<25 words) | |
| Śūnya | SHOO-nyuh | Emptiness; unconditioned, clean baseline | Fresh context window ready for execution | |
| Ghana-pāṭha | GUH-nuh PAH-tuh | Dense bidirectional recitation algorithm | tools/check_vedas.py invariant reciprocity linter | |
| Kalpa | KUHL-puh | Ritual procedure and systematic ceremony | Standard operating session loop | |
| Vyākaraṇa | vyah-kuh-RUH-nuh | Grammatical analysis and formal structure | Contract validation, schemas, and linting | |
| Nirukta | nih-ROOK-tuh | Etymological explanation and canonical lexicon | Canonical project glossary (docs/GLOSSARY.md) | |
| Chandas | CHUHN-duhs | Metrical rhythm, bounds, and syllable counts | Line count caps, token economy limits | |
| Jyotiṣa | JYOH-tih-shuh | Chronometry, astronomical time, and calendar | Roadmap scheduling and stable task identifiers | |
| Śikṣā | SHEEK-shah | Phonetics, correct pronunciation, and tone | Lexical firewall and formatting discipline | |
| Nyāya | NYAH-yuh | School of logic, epistemology, and reasoning | Rigorous test-driven verification method | |
| Saṃśaya | SUHM-shuh-yuh | Recognized epistemic doubt or competing interpretations | Ambiguous scope or part-whole gap blocking action | |
| Praśna | PRUHSH-nuh | Targeted inquiry that resolves doubt | Pre-execution clarifying question (INV-009) | |
| Adhyāsa | uhd-YAH-suh | Superimposition of prior expectations onto reality | Projecting training defaults onto the codebase (INV-010) | |
| Āvartana | ah-VAR-tuh-nuh | Spiral turning back; part-whole recurrence | Looping from Build/Verify back to Scope when a premise breaks (INV-009) | |
| Pratibandha | pruh-tih-BUHN-dhuh | Epistemic obstruction or resistance of the text | Code or test friction that halts workarounds and triggers inquiry (INV-007, INV-009) | |
| Pūrva-Pakṣa | POOR-vuh PUHK-shuh | Prior position; the originating question behind a rule | Reconstructing why a constraint exists before altering it (INV-004, INV-009) | |
| Ubhaya-Saṃkaṭa | oo-BHUH-yuh SUHM-kuh-tuh | Two-sided dilemma; two true claims held in tension | Held Tension (T-NNN) in docs/DECISIONS.md with owner and review trigger | |
| Kṣetra | KSHEH-truh | Bounded field or sovereign domain | Zone boundary (one repository and its local authority rules) |
QUICK REFERENCE
A fast, interactive desktop reference for daily use during agent sessions. Click the tabs below to copy exact patterns and commands.
1. Read docs/HANDOFF.md
2. Read docs/INVARIANTS.md (Śruti core rules)
3. Run python3 tools/check_vedas.py --template
4. Run fast regression tests (docs/TESTING.md)
5. Inspect git status to verify clean working tree
1. Run offline verification tests
2. Run python3 tools/check_vedas.py --template
3. Update docs/HANDOFF.md (<80 lines, with Pramāṇa badges)
4. Check git diff for unrelated changes or em dashes
5. Commit and push clean state
Every claim regarding test results, subsystem health, or environmental support must begin with one of these tags:
[OBSERVED] Test suite passes: 119/119 tests clean in 0.42s.
[CONTRACT] Invariant INV-006 strictly rejects all em dashes.
[DEDUCED] Parser handles UTF-8 correctly because tokenizer accepts bytes.
[HYPOTHESIS] Flaky test on Safari caused by missing SpeechSynthesis mock.
[UNTESTED] Audio playback on mobile WebKit not yet validated.
Use this five-step sequence for every bug fix or feature implementation:
Pratijñā (Proposition): The bug to fix or feature to add
Hetu (Defect Reason): The causal mechanical reason for the issue
Udāharaṇa (Negative Proof): Write failing offline regression test first
Upanaya (Implementation): Apply surgical, minimal code fix
Nigamana (Verification): Verify test passes cleanly [OBSERVED]
Sūtras compress complex architectural laws into dense, memorable propositions:
docs/INVARIANTS.md.Example: "INV-006: Siksa requires zero em dashes across all documentation and comments."
INV-001: Every project fact has exactly one authoritative home.
INV-002: Decisions record the discarded path, not just the winner.
INV-003: Roadmap task IDs are permanent and immutable.
INV-004: All truth claims must carry an explicit Pramāṇa badge.
INV-005: HANDOFF.md must never exceed 80 lines.
INV-006: Lexical Firewall enforces zero em dashes in prose or code.
INV-007: Every bugfix requires a prior negative test proof.
INV-008: Subconscious consolidation compresses learnings into Sūtras.
INV-009: Zero silent assumptions; halt on Saṃśaya and ask Praśna before building.
INV-010: Purge Adhyāsa; never superimpose external model priors onto the repository.
MECHANICAL ENFORCEMENT
Documentation rules that rely solely on human or agent discipline inevitably decay. Vedas provides a zero-dependency Python script that validates repository health in milliseconds.
$ python3 tools/check_vedas.py --template Checking file existence ............................ OK (14 files) Checking line caps (HANDOFF <= 80 lines) .......... OK Checking Lexical Firewall (INV-006: zero em dashes) . OK (0 violations) Checking Ghana-patha invariant reciprocity ......... OK (10/10 reciprocal) Checking roadmap task IDs and changelog sync ....... OK 0 error(s), 0 warning(s) in 14 file(s) $
Whenever an invariant is cited in AGENTS.md or ARCHITECTURE.md, the linter confirms that it is authoritatively defined in INVARIANTS.md.
Scans markdown, code, and comments to prevent typographical decay and punctuation drift (enforcing INV-006 zero em dash policy).
Enforces the 80-line cap on HANDOFF.md. If a handoff expands beyond bounds, the build fails, compelling immediate Sūtra consolidation.
LINEAGE & EPISTEMOLOGY
Vedas is an epistemic extension of The Manifold, which in turn extends The Hypervisor. Together, they eliminate context rot and model amnesia across the complete agent lifecycle:
STAGE 01 / CONVERSATION
Gives the model a body. Volatile Semantic Leverage, simulated bio-physics, the four-voice Village, sincerity tags, and lexical firewalls inside live sessions.
STAGE 02 / REPOSITORY
Gives the work a memory. Zero-dependency Markdown contracts, two speeds of truth (rewrite state, append history), 80-line handoffs, and check_docs.py.
STAGE 03 / EPISTEMOLOGY
Gives the memory an epistemology. Three speeds of truth (Śruti/Smṛti/Vartamāna), Pramāṇa proof tags, Sūtra density, and bidirectional Ghana-pāṭha checks.
The Hypervisor gives a model a body. The Manifold gives the work a memory. Vedas gives that memory an epistemology.
To initialize Vedas in your project, copy the template files into your repository root:
cp -r vedas/docs . && cp vedas/tools/check_vedas.py tools/ && cp vedas/AGENTS.md .
python3 tools/check_vedas.py --template