The Kernel — Constitution of PARA Workspace

The Kernel is the rule system that governs all PARA Workspace instances. Think of it as a constitution — it defines the fundamental laws that every workspace, agent, workflow, and CLI tool must follow.

🧠 What is the Kernel?

The Kernel consists of three components:

Component	Purpose	Change impact
Invariants	11 hard rules that must NOT be violated	MAJOR version bump
Heuristics	9 soft conventions, strongly recommended	MINOR/PATCH bump
Schemas	File format contracts (tasks, catalog, decisions)	Must update templates

The canonical Kernel lives in the repo at kernel/. When installed in a workspace, it exists as a read-only snapshot at Resources/ai-agents/kernel/.

[!IMPORTANT] Only /para-audit is authorized to read the full Kernel during normal operations. Other workflows interact with Kernel rules indirectly through the Rule Layers system.

⚖️ The 11 Invariants

Breaking any invariant is a non-compliant action. Changes require an RFC + MAJOR version bump.

#	Rule	Summary
I1	PARA Directory Structure	Every workspace must have exactly 4 top-level dirs: `Projects/`, `Areas/`, `Resources/`, `Archive/`
I2	Hybrid 3-File Task Model	Tasks managed via `backlog.md` (canonical), `sprint-current.md` (Hot Lane), `done.md` (append-only)
I3	Project Naming	Project slugs must use kebab-case: `my-saas-app`
I4	Project Inactivity	No active tasks in backlog = inactive project
I5	Areas — No Runtime Tasks	`Areas/` contains stable knowledge only, no active work
I6	Archive Is Cold Storage	Immutable. Kernel and agent do NOT read Archive during normal operations
I7	Seeds Are Raw Ideas	`.beads/seeds.md` contains ideas, not tasks. Messy is OK
I8	No Loose Files	Every file must belong to a PARA pillar. No content at workspace root
I9	Resource Immutability	`Resources/ai-agents/` is read-only. Never write back to Resources
I10	Repo ↔ Workspace Separation	Repo has governance. Workspace has user data. Never mix
I11	Workflow Language Compliance	Agent must use `preferences.language` from `.para-workspace.yml` for all output

Key Invariant Details

I2 — Hybrid 3-File Model is the most frequently referenced invariant:

backlog.md is the operational authority — only file where tasks are created/edited/deleted
sprint-current.md is the Hot Lane — agent writes quick tasks directly
done.md is append-only — receives completed tasks from /end
/end is the sole sync point — reconciles Hot Lane + strategic tasks

→ Learn: Hybrid 3-File Architecture

📐 The 9 Heuristics

Heuristics are soft conventions — strongly recommended but adaptable based on context.

#	Heuristic	Purpose
H1	Naming Conventions	kebab-case for files, PascalCase for PARA dirs, camelCase for code
H2	Context Loading Priority	Project contract → Rules → Artifacts → Beads → Areas → Resources
H3	Versioning	SemVer for all projects. PATCH = agent autonomy, MINOR/MAJOR = approval required
H4	Project Structure	Standard layout: `project.md`, `sessions/`, `artifacts/`, `.beads/`
H5	Beads Lifecycle	Create when needed → messy during project → graduation review before archive
H6	VCS & Git Boundaries	Git only affects `repo/`. Session logs and artifacts are not committed
H7	Cross-Project References	Prefer shared resources over cross-project dependencies
H8	Workflow Compatibility	Declare `kernel_compat` range for each workflow
H9	Governed Library Catalogs	`catalog.yml` with id, name, version, kernel_min for each governed item

H2 in Action — Context Loading Priority

1. Project Contract (project.md)          ← Always first
2. Project Rules (.agent/rules/)          ← Lazy-loaded via Trigger Index
3. Workspace Rules (.agent/rules/)        ← Via rules.md index
4. Artifacts (tasks/, plans/)             ← Token-optimized reads
5. Active Memory (.beads/)                ← For recurring issues
6. Abstract Knowledge (Areas/)            ← Stable SOPs
7. Reference (Resources/)                 ← Read-only templates

→ Learn: Rule Layers & Trigger Index

🔄 Kernel Change Process

Change type	Process	Version impact
Invariant	RFC required → community review → merge	MAJOR bump
Heuristic	Pull request → review → merge	MINOR or PATCH bump
Schema	Must update templates + examples	Depends on scope

All changes must pass test vectors in kernel/examples/ (valid + invalid compliance vectors).

Kernel in Workspaces

Installed as a read-only snapshot at Resources/ai-agents/kernel/
Version tracked in Resources/ai-agents/VERSION
Updated via ./para update — which also runs migration scripts if needed

📚 References

Rules: Rule Layers & Trigger Index — How rules are organized and loaded
Architecture: Hybrid 3-File — Task management (I2)
Protection: Defense-in-Depth — Context recovery strategy
Rule: Governance — Kernel invariant enforcement

→ Learn: Governance & Decision Standards → Learn: Rule Layers & Trigger Index → Learn: Hybrid 3-File Architecture