Security Model

Writ is built for environments where multiple autonomous agents have write access to the same codebase. That demands security guarantees that traditional VCS was never designed for.

Whether you’re running a zero trust setup where every agent action is verified, a fully autonomous system where agents operate without human oversight, or a mixed environment with humans in the loop. The security model is the same. Trust nothing by default. Verify everything cryptographically. Log every security relevant action.

Cryptographic Seal Chains

Every seal is linked to its predecessor through a chain of BLAKE3 hashes. Tamper with any seal and the entire chain breaks.

How It Works

Each seal contains three cryptographic fields:

Field	What It Hashes	What It Proves
`content_hash`	The seal’s own data (files, summary, metadata)	This seal hasn’t been modified
`parent_seal_hash`	The previous seal’s content	The previous seal is the real predecessor
`chain_hash`	Combination of content hash and parent seal hash	The entire history up to this point is intact

Verification

# Verify the full chain from genesis to HEAD
writ verify

# Verify a specific seal
writ verify --seal a7c2e8f4b31a

Both commands support --format json for programmatic consumption and --format human for readable output.

If any seal has been tampered with, verification reports exactly where the chain broke and what was expected versus what was found.

Ed25519 Signatures

Seals can be signed with Ed25519 digital signatures, authenticating who created them. Writ generates a dedicated convergence keypair on writ init, stored in .writ/keys/ with AES-GCM encryption and restricted file permissions (0600).

This means convergence seals (created by the engine during merge) are cryptographically distinguishable from agent seals (created by agents during work). You can always verify whether a merge result came from the convergence engine or was manually crafted.

Agent Identity

Every agent in writ is a registered entity, not just a string ID. In environments where dozens of agents have write access, knowing who did what, and being able to prove it cryptographically, is not optional.

Registration

writ agent register --id backend-dev --role implementer --trust-level standard

Trust Levels

Level	Description	Impact
Full	Project owner or lead. Unrestricted access.	Full confidence scoring in convergence.
Standard	Normal working agent. The default.	Standard confidence scoring.
Restricted	Limited scope. Constrained to specific files.	Reduced confidence caps. Changes more likely to be reviewed.
Untrusted	New or unverified.	Lowest confidence caps. Changes almost always escalated.

Trust levels directly affect convergence. When two agents’ changes conflict, the engine factors in their trust levels when scoring confidence. An untrusted agent’s changes receive lower confidence, making auto resolution less likely and human review more likely. This is how writ scales security across fleets of agents with varying levels of trust: from a known, verified lead agent to a newly introduced model that hasn’t earned trust yet.

Suspension and Revocation

Agents can be:

Suspended: Temporarily blocked from creating seals. All existing seals remain.
Revoked: Permanently deactivated. History preserved, but the agent cannot create new seals.

Both actions are recorded as security events in the audit log. In a fleet of autonomous agents, this is how you respond to a compromised agent immediately. Suspend it, review the damage, and all seals created after the compromise timestamp are automatically flagged.

Scope Enforcement

Specs declare which files they own. Agents can be constrained to specific files or directories.

How It Works

A spec declares its file scope: src/auth/*, tests/test_auth.py
An agent is registered with scope constraints
When the agent seals changes to files outside its scope, writ responds based on configuration:
- Warning mode (default): The seal succeeds but a scope violation is logged
- Enforce mode: The seal is rejected

Configuration

Scope enforcement is configurable:

# Warning mode (default): seal succeeds, violation logged
writ seal -s "updated config" --agent frontend-dev

# Enforce mode: seal rejected if out of scope
writ seal -s "updated config" --agent frontend-dev --enforce-scope

Visibility

Scope violations appear in three places:

writ context output (under scope violations)
Security event log (writ security events)
Integration risk scoring (violations increase the risk score)

No more agents silently modifying files they shouldn’t touch.

Content Traceability (In Development)

Content traceability is part of the LLM assisted convergence pipeline (Phase 5), currently feature flagged for a future release. When enabled, it enforces a strict rule: every line in merged output must trace back to an input (base, left, or right).

This will prevent:

Hallucinated content from leaking into merge results when an LLM is involved in resolution
Convergence bugs that might inject novel content
Silent data corruption during complex multi way merges

Security Event Monitoring

Writ maintains an append only security event log that records:

Event Type	When It Fires
`scope_violation`	Agent seals changes outside its declared scope
`chain_hash_failure`	Seal chain verification detects tampering
`authentication_failure`	Signature verification fails
`agent_revoked`	An agent is revoked or suspended
`convergence_low_confidence`	Convergence produces results below the confidence threshold
`unrecognized_agent`	A seal references an unknown agent ID

Viewing Events

# All events
writ security events

# Filter by severity
writ security events --severity warning

# Filter by event type
writ security events --event-type scope_violation

Events are severity classified (info, warning, critical) with configurable retention. GC can clean old events past their retention period, but the event log is append only during normal operation.

Summary

Layer	What It Protects
Hash chains	History integrity. No seal can be modified after creation.
Signatures	Authorship. Every seal can be verified back to its creator.
Trust levels	Convergence quality. Lower trust agents get more scrutiny.
Scope enforcement	File boundaries. Agents stay in their lane.
Content traceability	Merge integrity. No hallucinated or injected content survives. (In development, part of LLM convergence pipeline)
Event monitoring	Auditability. Every security relevant action is logged.

Next Steps

Seals vs Commits for the data model behind seal chains
Convergence for how trust levels affect merge decisions
Troubleshooting for common verification failures and how to resolve them

Keyboard shortcuts

writ-vcs Documentation