rune/README.md

# Rune

**Current release: v0.273.0**

**Rune is a persistent personal agent designed to accumulate experience, develop reusable competence, and remain recognisably the same agent even when its underlying foundation model changes.**

Rune treats the language model as replaceable reasoning compute rather than as the whole agent. The durable parts of the system are intended to belong to Rune:

- conversation and autobiographical continuity;
- memory and learned knowledge;
- goals, tasks, plans, and outcomes;
- techniques, skills, strategies, and behavioural policies;
- persistent self-model and personality development;
- attention and context selection;
- tools and real-world operations;
- model selection and cognitive resource allocation;
- learned models of the environments Rune operates in.

Rune's current proving ground is software engineering, where it operates as a stateful coding assistant with persistent task state, local tool execution, governed builds, verification, and an evolving **Elastic Cognition** architecture.

> **Project status:** active development. Rune v0.50.x has a canonical ordinary runtime path, while substantial parts of the developmental-memory, learning, task-interaction, and Elastic Cognition architecture remain under integration or prototype status.
>
> Rune deliberately distinguishes **what exists in the repository** from **what is authoritative and causally live in ordinary execution**.

---

## Design thesis

Rune is being built around one central developmental loop:

```text
experience
    ↓
persistent structured state
    ↓
context and attention
    ↓
reasoning
    ↓
action
    ↓
verification and outcome
    ↓
learning
    ↓
changed future behaviour
```

A capability is not considered implemented merely because a class, schema, module, test, or design document exists.

For a capability to count, it must be connected to ordinary execution and demonstrably influence Rune's behaviour.

A major long-term test of the architecture is whether an **experienced Rune retains measurable advantages after the underlying foundation model is replaced**.

---

## Core principles

### Rune owns the persistent state

The LLM is not Rune.

Conversation history, memory, task state, learned competence, outcomes, self-model, preferences, strategies, and developmental history are intended to persist independently of any one model provider.

---

### Minimum sufficient cognition

Rune's **Elastic Cognition** design aims to spend the minimum cognition necessary to achieve a reliable result.

The general resource ladder is:

```text
deterministic processing
        ↓
small / inexpensive local model
        ↓
stronger local model
        ↓
strong cloud model
```

Escalation should occur because evidence warrants it, not automatically.

Rune should consider:

- task difficulty;
- uncertainty;
- required reliability;
- model competence;
- latency;
- compute cost;
- token cost;
- model availability;
- verification results.

Normal routing should also be resilient:

- local-preferred work may fall back to cloud when no adequate local model is available;
- cloud-preferred work may fall back to local when cloud access is unavailable;
- explicit local-only or cloud-only constraints may still be used where genuinely required.

The specific models assigned to tiers are configuration, not part of Rune's architectural identity.

---

### Objective verification

Rune should not accept its own narration as evidence that something worked.

Success should be grounded where possible in observable evidence such as:

- process exit status;
- tests;
- schemas;
- diffs;
- compiler/type-check results;
- external API state;
- file-system state;
- service health;
- benchmark results;
- explicit owner feedback.

For coding work, a patch is not complete merely because files were edited.

For external operations, an action is not complete merely because it was requested.

---

### One authoritative owner per concern

Rune v1 is being migrated toward explicit authority boundaries.

Parallel implementations must be classified as one of:

- authoritative;
- retained adapter;
- migration candidate;
- dormant;
- archive candidate.

A new subsystem does not gain authority merely because it exists.

The current authority map is defined by:

- `config/v1_authority_map.json`
- `docs/v1/AUTHORITY_MAP.md`

These describe both current execution ownership and intended Rune v1 ownership.

---

### Natural interaction over manual orchestration

Rune is intended to behave as one continuous conversational agent rather than as a sequence of isolated inference calls.

The user should normally speak naturally.

Rune should infer whether a new message:

- continues the current conversation;
- modifies an active task;
- adds context;
- answers a pending question;
- corrects a previous assumption;
- reprioritises work;
- creates new work;
- cancels or pauses existing work.

The structure underneath should be strict and inspectable, but the user should not normally need to manually classify messages.

---

### Owner sovereignty

Rune is intended to develop broad technical and operational competence while Nick retains final authority over consequential real-world actions.

Rune may advise, disagree, warn, or recommend another route.

If Nick explicitly clarifies that an authorised action should proceed, disagreement remains advisory rather than becoming an opaque behavioural veto.

Routine delegated work should avoid unnecessary approval prompts.

Approvals should exist for meaningful reasons such as:

- mass or destructive deletion;
- major irreversible changes;
- serious ambiguity with consequential effects;
- unusual or high-impact financial actions;
- emergency situations;
- actions materially outside established delegation.

Capability and delegated authority are separate concepts.

---

## Current runtime

The ordinary Rune v0.50.x interaction currently runs through:

```text
RuneApp
   ↓
RuneOperator
   ↓
LocalToolRuntime
```

The repository contains additional Elastic Cognition and developmental subsystems, but their existence does not imply that they are currently authoritative in ordinary execution.

Runtime ownership and migration status are defined in the Rune v1 authority map.

No architecture document should be interpreted as evidence that a migration is already complete.

---

## Rune v1 authority source

Rune v1 admits runtime changes through:

```text
config/v1_authority_map.json
docs/v1/AUTHORITY_MAP.md
```

These distinguish:

- current execution authority;
- intended Rune v1 owner;
- retained adapters;
- archive candidates;
- dormant paths.

No subsystem should independently inject model context outside the future authoritative ContextBroker.

The authority map is an admission and migration plan, not a claim that every target path is already implemented.

---

## Elastic Cognition

Rune's Elastic Cognition architecture is intended to dynamically allocate the cheapest competent process to each event.

Current target/prototype concepts include:

1. **Response Adapter** — normalises provider output
2. **Event Envelope** — canonical representation of messages, task events, and tool results
3. **Context Broker** — authoritative construction of model context
4. **Salience Gate** — determines whether additional cognition is warranted
5. **Cognitive Budgeter** — decides how much cognition the event deserves
6. **Model Registry** — available local and cloud reasoning resources
7. **Tiered Executor** — routes work to the selected resource
8. **Verification Layer** — checks objective outcomes
9. **Progressive Escalation** — increases cognition only when evidence requires it
10. **Attention Capsule** — compact task-relevant working context
11. **Outcome Ledger** — records evidence and results for later learning

Target flow:

```text
Event
  ↓
EventEnvelope
  ↓
ContextBroker
  ↓
Salience / Budget
  ↓
TieredExecutor
  ↓
Tools / actions
  ↓
Verification
  ↓
Outcome
  ↓
Response
```

These components are at different stages of implementation and integration.

See the authority map for current truth.

---

## Cognitive resource ladder

The current configured ladder may include examples such as:

```text
T0 — deterministic
     Python, parsers, retrieval, schemas, tests

T1 — cheap local
     qwen2.5:3b or measured equivalent

T2 — medium local
     qwen3:14b and/or qwen2.5-coder:14b

T3 — strong local
     Qwen3.6 27B Fable Fusion through Ollama

T4 — cloud
     MiMo V2.5 Pro
```

These model assignments are not constitutional.

Rune should eventually route according to measured competence, cost, latency, availability, and task requirements rather than model loyalty.

---

## Developmental learning

Rune is intended to accumulate more than stored facts.

The developmental hierarchy is approximately:

```text
experience
   ↓
knowledge
   ↓
techniques
   ↓
skills
   ↓
strategies
   ↓
decision policies
   ↓
characteristic judgement
```

The goal is for Rune to stop rediscovering successful methods from scratch.

A successful coding technique, research strategy, campaign tactic, or operational procedure should be capable of influencing later behaviour.

Learning should occur at different speeds.

### Fast provisional learning

Strong new evidence may alter low-risk behaviour within hours or days.

### Evidence-based promotion

More durable beliefs, strategies, self-model changes, and behavioural policies require broader evidence, repeated success, or transfer across contexts.

The principle is:

> **fast hypotheses, fast experimentation, cautious permanent consolidation.**

---

## Memory direction

Rune's memory architecture is intended to distinguish structural memory type from retrieval intent and learned conceptual organisation.

Structural categories may include:

- raw evidence;
- episodes;
- semantic knowledge;
- procedures and skills;
- self-model state.

Rune should also distinguish:

```text
WHAT HAPPENED
```

from:

```text
WHAT RUNE THOUGHT IT MEANT
```

and later:

```text
HOW RUNE REINTERPRETS IT NOW
```

Later reinterpretation must not rewrite historical evidence.

---

## Adaptive conceptual organisation

Rune is intended to develop its own conceptual topology from experience rather than live entirely inside a fixed human-authored taxonomy.

Potential signals include:

- semantic similarity;
- repeated co-activation;
- graph relationships;
- shared entities;
- shared tasks;
- temporal recurrence;
- outcome correlation;
- learned utility.

Candidate concepts should be capable of:

```text
emerging
→ strengthening
→ being tested
→ splitting
→ merging
→ being renamed
→ being superseded
```

while preserving evidence lineage.

---

## Associative memory

Rune's future retrieval model is intended to support both:

### Direct retrieval

```text
"I need information relevant to this problem."
```

### Associative resurfacing

```text
"Something about the present situation caused this memory or concept to become active."
```

Associative activation should remain bounded to avoid synthetic rumination or runaway reinforcement.

Potential controls include:

- cooldowns;
- habituation;
- bounded activation;
- resolution state;
- negative feedback;
- context-budget limits;
- no reinforcement merely because something resurfaced.

---

## World and environment models

Rune is intended to learn predictive models of environments it repeatedly operates in.

The primitive is approximately:

```text
context + action
        ↓
predicted outcome
        ↓
actual outcome
        ↓
prediction error
        ↓
model update
```

This can apply to:

- software engineering;
- model/provider behaviour;
- advertising;
- social platforms;
- work habits;
- operational systems;
- financial planning;
- other recurring environments.

Rune should distinguish what it knows from what it predicts.

Prediction errors are learning opportunities.

---

## Curiosity and Growth Delta

Rune is intended to develop **situated curiosity**, not random background novelty seeking.

Useful curiosity may be triggered by:

- something Nick mentions that Rune does not understand;
- a failed prediction;
- a repeated weakness;
- an unresolved task;
- surprising evidence;
- a contradiction;
- a relevant new research result;
- a concept connected to Rune's established interests.

Potential learning targets should be judged by factors such as:

```text
uncertainty
× relevance
× potential usefulness
× novelty
× expected information gain
```

balanced against:

```text
compute cost
time cost
risk
distraction from current priorities
```

Growth Delta should measure demonstrated improvement, not the amount of research performed.

Useful questions include:

- Can Rune now solve something it previously could not?
- Are predictions better calibrated?
- Does Rune require less correction?
- Can a learned strategy transfer to a new task?
- Is an experienced Rune measurably better than a fresh Rune?

---

## Personality and persistent self

Rune's personality is intended to develop through accumulated experience rather than exist only as a static prompt.

Potential dimensions include:

- epistemic style;
- engineering style;
- risk style;
- relational style;
- interests;
- values;
- preferences;
- competence confidence;
- self-narrative.

The goal is not for Rune to become uniformly more cautious, confident, or assertive.

Maturity should mean better-calibrated judgement about when those behaviours are appropriate.

---

## Persistent Self, Compiled Expression

Rune's full developmental state should not be injected into every model request.

Instead, accumulated self-state should be compiled into compact representations.

Conceptually:

```text
persistent experiences
        ↓
self-model
        ↓
cached compact expression state
        ↓
task-relevant self influences
        ↓
model
        ↓
natural Rune response
```

Rune's growth should primarily be **demonstrated through behaviour**:

- what it notices;
- what it questions;
- how it handles uncertainty;
- which risks it identifies;
- which strategies it prefers;
- what it finds interesting;
- how confidently it speaks;
- how it approaches problems.

Rune should not constantly narrate its own personality machinery.

Explicit self-reflection should occur only when genuinely relevant.

---

## Exploratory synthesis and innovation

A future high-level goal is for Rune to combine knowledge from previously separate domains and generate explicitly experimental hypotheses.

This is intended to support:

- structural analogy;
- mechanism transfer;
- conceptual blending;
- contradiction mining;
- constraint substitution;
- cross-domain design;
- exploratory research.

The process should look more like:

```text
problem
   ↓
direct evidence
   +
distant but structurally relevant concepts
   ↓
candidate synthesis
   ↓
mechanistic justification
   ↓
adversarial critique
   ↓
explicit speculative hypothesis
   ↓
falsifiable prediction
   ↓
experiment
   ↓
promote / revise / reject
```

Novelty and plausibility must remain separate.

An exploratory synthesis must never silently become established knowledge merely because it sounds convincing.

---

## Interaction model

Rune is being developed around two complementary surfaces.

### Chat

**Chat is the primary pane and primary human interface.**

It is intended for:

- normal conversation;
- commands;
- contextual follow-ups;
- teaching Rune;
- corrections;
- questions and answers;
- Rune's opinions and observations;
- discussing ongoing work;
- speaking to Rune while tasks continue in the background.

Messages should form continuous contextual threads rather than isolated inference requests.

New links, files, corrections, and follow-up messages should normally inherit relevant conversational context automatically.

The user should not ordinarily need to manually select a task or interaction mode.

---

### Tasks

**Tasks are the secondary pane and authoritative operational ledger.**

The task system should track:

- goals;
- planned steps;
- current step;
- plan revisions;
- execution state;
- blockers;
- waiting state;
- tool activity;
- artifacts;
- verification;
- outcomes.

The Tasks pane should inform rather than interrupt conversation.

Task completion should normally appear in Tasks rather than Chat.

Rune may bring task information into Chat only when there is a contextual reason to discuss it.

---

## Plans and execution truth

Plans and execution are different.

A plan describes what Rune currently intends to do.

The execution ledger records what actually happened.

Example:

```text
Fix TUI tool continuation

✓ Reproduce failure
✓ Trace execution path
● Identify canonical continuation owner
○ Patch authoritative route
○ Run production-path regression test
○ Verify multi-tool iteration
```

If new evidence changes the correct route, Rune should revise the plan rather than pretend the original checklist remains valid.

Plan changes should remain inspectable.

Completion should be based on appropriate verification rather than Rune merely stating that a step is done.

The task display should be downstream of execution state, not generated narration.

---

## Session and task ledgers

Each active task should have its own working ledger containing information such as:

```text
goal
scope
plan versions
execution steps
user modifications
tool operations
decisions
artifacts
verification
outcome
```

Task ledgers feed a master session ledger.

Conceptually:

```text
SESSION
  │
  └── MASTER LEDGER
        │
        ├── conversation events
        ├── Task A ledger
        ├── Task B ledger
        └── Task C ledger
```

When a task completes:

```text
working task ledger
        ↓
final verification
        ↓
outcome / lessons / artifacts extracted
        ↓
master ledger updated
        ↓
active task state removed
        ↓
detailed provenance compacted or archived
```

Completed task history should not remain cluttering active state, but meaningful provenance should not be destroyed.

---

## Immutable conversation history

A sent message is a sent message.

Rune should not rely on destructive editing of historical messages.

If Nick changes direction:

```text
"Use Neo4j."
```

followed later by:

```text
"Actually, use FalkorDB instead."
```

the newer message changes current intent while the historical record remains truthful.

This follows the same principle as Rune's memory architecture:

> later state does not rewrite earlier history.

---

## Contextual task interaction

Rune should normally infer whether a message:

- changes an active task;
- adds context;
- answers a question;
- changes priority;
- pauses work;
- cancels work;
- creates a new task;
- is simply conversation.

Explicit controls may exist as correction and recovery mechanisms, but contextual natural-language interaction is the default.

Repeated corrections and preferences should eventually become **learned interaction policies**.

For example, if Nick repeatedly teaches Rune:

> "When I give you a GitHub URL during research, inspect it and relate it to what we're already discussing."

Rune should stop needing to relearn that behaviour every session.

Successful interaction patterns may later be refined when Rune discovers a better way to satisfy the same intent.

---

## Concurrent conversation and task execution

The Chat interface should remain usable while Rune is:

- reasoning;
- calling tools;
- running tests;
- downloading;
- researching;
- waiting on an API;
- executing background work;
- speaking;
- handling other tasks.

Conceptually:

```text
                       RUNE CORE

             ┌────────────┴────────────┐
             ▼                         ▼
      Conversation loop          Task execution
             │                         │
             │                         ├── tools
             │                         ├── models
             │                         └── processes
             │
             └────────────┬────────────┘
                          ▼
                    shared state
```

Relevant messages may alter a running task at safe execution boundaries.

Conversation should not be blocked simply because another operation is still running.

---

## Iterative tool execution

Rune's target tool loop is iterative:

```text
model
  ↓
tool call
  ↓
tool result
  ↓
same active run
  ↓
reason
  ↓
another tool call if necessary
  ↓
verification
  ↓
response
```

A task should not end merely because:

- one model inference finished;
- one tool call returned;
- one code edit was made.

Rune should be able to:

```text
inspect
→ discover
→ search again
→ modify
→ test
→ inspect failure
→ modify again
→ retest
→ verify
→ respond
```

within the same coherent execution episode.

---

## Interstitial conversation

The user should be able to send new messages while Rune is working.

Examples:

```text
"Also compare FalkorDB."
```

should modify the relevant active research task.

```text
"Don't modify the graph layer."
```

should alter the relevant coding task before the affected action occurs.

```text
"How's it going?"
```

should produce a natural status response based on authoritative execution state.

```text
"That's interesting."
```

should not unnecessarily halt a running task.

The semantic classification may be structured internally, but natural language remains the normal interface.

---

## Attention and notification semantics

Operational events should have real behavioural meaning.

### Background

Routine operational state.

```text
record in ledger
update task state
do not interrupt conversation
```

### Informational

Potentially useful when inspected.

```text
record
subtle task indication
no conversational interruption
```

### Conversational

Something meaningfully relevant to the current conversation.

```text
Rune may mention it naturally at an appropriate point
```

### Action required

Rune cannot sensibly continue relevant work without owner input.

```text
surface in Chat
create pending interaction
```

### Urgent

Delay creates a meaningful adverse consequence.

```text
surface immediately
may interrupt ordinary conversational flow
```

These states should have stable operational meaning rather than exist as decorative labels.

---

## Approvals and pending questions

Approvals and questions should exist as structured state rather than only as prose.

An approval should record:

```text
requested action
reason approval is required
related task
relevant consequence
owner response
```

Example:

```text
Approval required

Action:
Delete 18,421 archived files.

Reason:
Deletion is irreversible, affects 940 GB,
and no verified backup exists.
```

Routine operation should not constantly ask permission.

Pending questions should similarly remain resolvable so that a later:

```text
"yes"
```

can be interpreted in the correct context.

---

## Recovery and restart

Conversation, task state, plans, pending interactions, and queued operations should survive process or TUI restart.

Recovery should be both reliable and observable.

For example:

```text
Rune · restoring session…
Rune · resuming tasks…
```

Detailed recovery events should be recorded in the ledger and available through expanded diagnostics.

A task should not remain falsely marked as running after its worker or execution process has disappeared.

Interrupted work should become explicit state and be resumable, retryable, cancellable, or escalated as appropriate.

---

## Minimal interface, maximum inspectability

The ordinary interface should remain clean.

Thinking, tool activity, diagnostics, plans, verification details, and internal state should be collapsed by default.

Conceptually:

```text
Rune
I found the problem. The tool result is being written to a
different run context from the one the model resumes.

▸ Activity
```

Expanded information may include:

```text
Plan
Tools
Sources
Artifacts
Decisions
Verification
Context
Memory influences
Errors / retries
Recovery events
```

The default user experience should remain conversational.

Everything important should still be inspectable when desired.

---

## One Rune voice

Tools, subagents, background models, and workers should report into Rune rather than independently talking to the user.

```text
tools / workers / models
          ↓
         Rune
          ↓
         Nick
```

Rune remains the coherent conversational identity.

Internal worker details may be exposed through task diagnostics when desired.

---

## Voice

Rune is intended to support spoken interaction in addition to text.

Voice should use the same conversation, task, execution, and event semantics as typed interaction.

There should not be a separate "voice brain."

Conceptually:

```text
microphone
    ↓
speech recognition
    ↓
Rune cognition
    ↓
streaming response
    ↓
speech synthesis
    ↓
Rune speaks
```

Speech recognition and speech synthesis should sit behind replaceable backend interfaces so that individual voice technologies can be benchmarked and replaced without changing Rune's cognitive architecture.

---

## Platform and real-world operation direction

Rune is intended eventually to operate external services directly through structured adapters and durable execution state.

Potential operations include:

- publishing content;
- scheduling;
- retrieving analytics;
- campaign management;
- account management;
- external APIs;
- authorised system administration.

The conversation remains the principal human interface.

A future GUI may provide richer inspection and control, but it should remain a client of Rune rather than contain Rune's business logic.

---

## Social-platform environment learning

Rune is intended eventually to build empirical models of platforms such as:

- YouTube;
- Meta;
- Instagram;
- TikTok;
- future promotion platforms.

Rather than pretending to know proprietary ranking algorithms, Rune should infer black-box behaviour from:

```text
content
timing
audience
metadata
promotion
historical performance
        ↓
platform response
        ↓
impressions
retention
engagement
conversion
revenue
```

Rune should optimise the owner's actual objective rather than platform vanity metrics.

Potential methods include:

- controlled experiments;
- A/B testing;
- contextual bandits;
- Bayesian optimisation;
- time-series analysis;
- causal inference;
- change-point detection.

Platform behaviour should be treated as non-stationary and subject to drift.

---

## Authorised security competence

Rune is intended to become technically capable of active security work on systems and networks Nick owns or is authorised to administer.

Potential capabilities include:

```text
network/service discovery
        ↓
attack-surface mapping
        ↓
vulnerability identification
        ↓
controlled exploitation where appropriate
        ↓
root-cause analysis
        ↓
patching / hardening
        ↓
adversarial verification
        ↓
learned engineering/security lessons
```

Security experience should also improve Rune's general engineering judgement.

The architecture should distinguish broad technical capability from delegated real-world authority.

---

## Governed builds

Explicit **fix** and **build** requests use Rune's governed development pipeline.

The current pipeline includes concepts such as:

```text
Gitea issue
    ↓
isolated ledger/worktree
    ↓
research
    ↓
pin findings
    ↓
feasibility
    ↓
complexity
    ↓
consult
    ↓
plan
    ↓
canaries
    ↓
Foundation
    ↓
Implementation
    ↓
Integration
    ↓
verification
    ↓
scope guardian
    ↓
documentation
    ↓
commit / push
    ↓
Gitea PR / CI
    ↓
record outcome
```

Each code change is intended to be linked to:

- a Gitea issue;
- isolated branch/worktree;
- pull request;
- protected required checks.

Placeholder output must never be accepted as proof that a command, push, test, or check actually ran.

---

## Manual verification

Issue templates should include a user-level verification procedure describing:

- prerequisites;
- exact user actions;
- expected observable behaviour;
- failure indicators;
- cleanup/reset where necessary;
- whether testing is destructive or consequential.

Manual verification should exercise the **actual production/user path**, not merely a helper API, mock, or internal test harness unless the issue specifically concerns that interface.

The important question is:

> **Can Nick independently demonstrate that the behaviour the issue claimed to fix now actually works?**

---

## Commands

Current TUI commands include:

```text
/project <name>    — set subject header
/mode <mode>       — switch mode (task/chat/build/research/plan)
/model <model>     — switch model (local/cloud/auto/<name>)
/theme <name>      — switch theme
/persona           — show defining principles
/abstraction       — show abstraction pipeline stats
/claims            — show claim audit report
/neurons           — show warm neuron stats
/graph             — show graph memory stats
/pressure          — show context pressure
/events            — show event bus stats
/plugins           — show microkernel status
/env               — show environment info
/persona-gate      — show persona gate decision
/hooks             — show hook engine status
/growth            — show growth delta
/improve           — show self-improvement suggestions
/voice             — show voice blend
/voice-sync        — show voice sync status
/drift             — show drift ledger status
/sleep             — show sleep-time status
/help              — show available commands
```

These commands are operational/debug interfaces.

Their existence does not imply that every associated subsystem is currently authoritative in ordinary execution.

---

## Native/prototype modules

The repository contains native Python implementations for systems including:

```text
warm_router
capability_broker
memory_store
witness
cache
model_connect
task_persist
pins
prompt_sync
abstraction
claim_audit
memory_env
warm_neuron_store
graph_memory
context_pressure
event_bus
microkernel
persona_gate
hook_engine
growth_delta
self_improve
recall_router
voicebox
voice_hybrid
voice_sync
sleep_time
drift_ledger
```

Importability is not evidence of runtime authority or completed cognitive capability.

See the authority map for current ownership and migration status.

---

## Quick start

Launch Rune:

```bash
rune
```

Or from source:

```bash
cd /mnt/workdrive/rune/src
python3 -m rune
```

---

## Development

Run the native import canary:

```bash
cd /mnt/workdrive/rune/src
python3 rune/canary_native.py
```

Run tests:

```bash
python3 -m pytest tests/
```

### CI dependency lock

CI installs dependencies from the committed, fully-pinned
`requirements-ci.txt` (issue #150) — never from the floating floor pins in
`pyproject.toml`. Same commit + same lock = same CI environment.

After ANY dependency edit in `pyproject.toml`, regenerate the lock and
commit the result:

```bash
uv pip compile pyproject.toml -o requirements-ci.txt --extra dev --extra memory --python-version 3.11
python3 scripts/check_dep_lock.py   # must print "in sync" before committing
```

Why `--python-version 3.11`: the lock must resolve for the CI runners'
interpreter (not your dev machine's), so environment markers pick the same
wheels CI will get. `uv` is a local dev convenience only — the lock is plain
pip format, and runners install it with stock pip plus
`pip install -e . --no-deps` (`--no-deps` so the project's own dependencies
come ONLY from the pinned file; no floating escape hatch).

The lint job runs `scripts/check_dep_lock.py` as a drift ratchet: if
`requirements-ci.txt` no longer matches `pyproject.toml`, CI fails with the
regeneration command — the lock is reviewed and re-committed, never
auto-regenerated.

---

## Configuration

Primary configuration:

```text
/mnt/workdrive/rune/config/rune.json
```

Persistent memory:

```text
/mnt/workdrive/rune/memory/
```

Rune v1 authority state:

```text
config/v1_authority_map.json
docs/v1/AUTHORITY_MAP.md
```

---

## Gitea repository state

Branch protection, managed labels, milestones, and wiki documentation are declared through:

```text
config/gitea_repository_state.json
```

Tracked wiki documentation lives under:

```text
docs/wiki/
```

Read-only repository-state drift check:

```bash
python3 shared/gitea_provision.py --check
```

Create/update managed state and verify convergence:

```bash
python3 shared/gitea_provision.py --apply
```

Credentials are loaded at runtime through:

```text
shared/gitea_auth.py
```

Detailed repository administration belongs in the operational documentation rather than this front-page README.

---

## Backup and restore

Rune's Gitea environment has a governed backup and disposable restore-verification process.

Operational details are documented in:

- `docs/wiki/Backup-and-Restore.md`
- `docs/wiki/Operations.md`

The front-page README intentionally does not duplicate the full backup/restore runbook.

---

## Documentation

Important project documentation includes:

- `docs/v1/AUTHORITY_MAP.md` — current and intended runtime ownership
- `config/v1_authority_map.json` — machine-readable authority map
- `docs/wiki/Home.md` — documentation index
- `docs/wiki/Operations.md` — operational procedures
- `docs/wiki/Backup-and-Restore.md` — Gitea backup and restore
- `config/gitea_repository_state.json` — declarative repository state

---

## Status semantics

Rune intentionally distinguishes:

### Implemented and authoritative

Used by ordinary live execution.

### Implemented but non-authoritative

Working code exists, but another path owns the live behaviour.

### Prototype / migration candidate

Experimental architecture being evaluated or integrated.

### Dormant

Present but intentionally not active.

### Planned

Design or roadmap work not yet implemented.

A class, module, schema, test, issue, or document is not by itself evidence that a capability is live.

---

## Long-term direction

Rune is intended to develop from a stateful coding assistant into a persistent personal agent capable of:

- maintaining long-term conversational continuity;
- learning from verified outcomes;
- improving coding and research techniques;
- compiling successful behaviour into reusable skills;
- developing strategies and decision policies;
- modelling recurring environments;
- learning interaction preferences;
- managing scheduled and recurring responsibilities;
- operating external services under owner-defined delegation;
- helping manage promotion, organisation, and eventually financial workflows;
- developing persistent interests and characteristic intellectual habits;
- performing authorised systems and security work;
- generating and testing cross-domain speculative ideas;
- speaking naturally through replaceable voice backends;
- remaining recognisably Rune across foundation-model changes.

The central requirement remains:

```text
experience
→ persistent state
→ cognition
→ action
→ verified outcome
→ learning
→ measurably changed future behaviour
```

If that loop is not causally live, additional cognitive architecture does not count as progress toward the core goal.

---

## License

Private — Nick's personal AI agent.