UCIRS

Unified Cognitive Infrastructure for Irreversible Systems

A structural enforcement layer for Git workflows. UCIRS detects irreversible actions in commits and requires explicit assumption declarations before proceeding.

---

What This Is

UCIRS is a Git hook system that:

• Detects patterns indicating irreversible changes (database migrations, destructive operations, API breaking changes)
• Blocks commits when irreversible changes lack explicit assumptions
• Explains why a block occurred and what to do next
• Records enforcement decisions for later reconstruction

What This Is Not

• A security scanner
• A vulnerability detector
• A code quality tool
• An AI system that "understands" code

Limitations

1. Pattern-based detection: UCIRS uses regex patterns to identify irreversible actions. Novel patterns not in the detection rules will not be caught.
2. No semantic understanding: UCIRS cannot determine if an assumption is correct, only that one exists.
3. Local enforcement only: Cross-repo features (v3+) propagate warnings, never blocks.
4. Heuristic classification: Security detection (v4) uses content patterns with explicit confidence levels.

---

Installation

npm (CLI + Library)

# Global install for CLI
npm install -g ucirs

# Local install for library API
npm install ucirs

VS Code Extension

ext install asapabhii.ucirs

Or search "UCIRS" in VS Code Extensions.

Git Hooks

After installing, add hooks to your repository:

ucirs install-hooks

Quick Start

1. Make an irreversible change

-- migrations/001_drop_column.sql
ALTER TABLE users DROP COLUMN legacy_field;

2. Attempt to commit

git add migrations/
git commit -m "drop legacy column"

3. UCIRS blocks with explanation

╔══════════════════════════════════════════════════╗
║              UCIRS PAUSED COMMIT                 ║
╚══════════════════════════════════════════════════╝

WHAT HAPPENED:
  No assumption declared for this change

WHY IT MATTERS:
  Irreversible changes need an explicit assumption before proceeding

WHAT WAS DETECTED:
  • migrations/001_drop_column.sql: HIGH irreversibility

WHAT TO DO NEXT:
  1. Declare an assumption in .ucirs/assumptions.yaml
  2. Split into smaller, reversible commits
  3. Adjust the change to avoid irreversible patterns

4. Declare an assumption

Create .ucirs/assumptions.yaml:

assumptions:
  - id: "asm/20241221/migrations/a1b2"
    description: "Column removal tested on staging with 50k records. No active queries use this column."
    scope:
      files:
        - "migrations/"
      services: []
    origin:
      type: manual
      ref: "JIRA-1234"
    timestamp: "2024-12-21T10:00:00Z"
    dependencies: []
    status: active

5. Commit succeeds

git commit -m "drop legacy column"
# [main abc1234] drop legacy column

---

Assumption Schema

Required Fields

Field	Type	Description
id	string	Unique identifier. Auto-generated format: asm/YYYYMMDD/scope/hash
description	string	Human-readable explanation of what was verified
scope.files	string[]	File patterns this assumption covers
scope.services	string[]	Service names this assumption covers
origin.type	enum	commit, merge, deploy, manual
origin.ref	string	Reference (PR number, commit hash, ticket ID)
timestamp	ISO-8601	When the assumption was created
dependencies	string[]	IDs of assumptions this depends on
status	enum	active, aged, expired, unknown

Optional Fields (v2+)

Field	Type	Description
createdAt	ISO-8601	Explicit creation timestamp
expiresAt	ISO-8601	When assumption becomes invalid
reviewAfter	ISO-8601	When assumption should be reviewed
provenance.triggeringDetector	string	Pattern that triggered enforcement
provenance.filesInvolved	string[]	Files that caused the trigger

Optional Fields (v3+)

Field	Type	Description
crossRepo.declaredIn	string	Repository where assumption was created
crossRepo.dependedBy	string[]	Repositories depending on this assumption
crossRepo.visibility	enum	local, linked
trust.level	enum	local, team, org
trust.reviewers	string[]	Who validated this assumption
ownedBy.team	string	Responsible team
ownedBy.contact	string	Contact email or handle

Optional Fields (v4)

Field	Type	Description
security.relevant	boolean	Whether this is security-related
security.rationale	string	Why this is security-relevant
security.category	enum	access_control, data_exposure, auth_bypass, encryption, logging, api_exposure, permission_change, other
relatedVulnerabilities	array	References to CVEs or internal IDs (for context only, no scanning)

Optional Fields (v5)

Field	Type	Description
topology.links	array	Structural relationships to other assumptions (amplifies, masks, weakens, depends_on)
epistemicDebt.description	string	What is unknown (unresolved unknowns)
epistemicDebt.introducedAt	ISO-8601	When the unknown was introduced
epistemicDebt.scope	enum	local, cross-repo, org-wide
reasoningContext.mode	enum	under_time_pressure, incident_response, exploratory, cost_driven, normal
reasoningContext.notes	string	Optional notes about decision context

---

What UCIRS Detects

UCIRS detects irreversible decision pressure + assumption risk — not bugs, CVEs, or code quality issues.

Database & Data Layer

Pattern	Level	Examples
Schema changes	HIGH	DROP TABLE, DROP COLUMN, ALTER COLUMN TYPE, ADD NOT NULL
Data deletion	EXTREME	DELETE FROM without WHERE, TRUNCATE, bulk deletes
Migration patterns	HIGH	One-way migrations, backfill without verification

API & Interface Changes

Pattern	Level	Examples
Public API changes	HIGH	Removing endpoints, changing response shape, removing fields
Contract drift	MEDIUM	OpenAPI/GraphQL schema changes, versionless mutations

Auth, Permissions & Security

Pattern	Level	Examples
Permission broadening	HIGH	IAM role expansion, *:* permissions, relaxed ACLs
Exposure changes	HIGH	Internal → public service, private bucket → public
Encryption & secrets	EXTREME	Changing encryption modes, logging sensitive data, hardcoded secrets

Filesystem & Infrastructure

Pattern	Level	Examples
Destructive actions	EXTREME	rm -rf, recursive deletes, config overwrites
Infrastructure changes	HIGH	Terraform destroy, resource deletions, region changes

Deployment & Config

Pattern	Level	Examples
Deployment coupling	MEDIUM	Schema + code changes together, breaking change without feature flags
Config drift	MEDIUM	Env var changes, feature flag deletions, default value changes

Cross-Repo & System-Level (v3+)

Pattern	Level	Examples
Cross-repo dependencies	MEDIUM	One repo assuming behavior of another, implicit coupling
Cross-repo drift	MEDIUM	Assumption updated in one repo, downstream repos stale

Assumption & Epistemic Signals (v5)

Pattern	Level	Examples
Missing assumptions	BLOCKING	Irreversible change with zero assumptions
Aged/expired assumptions	WARNING	Assumptions older than declared validity
Scope drift	WARNING	Change affects files outside assumption scope
Contradictions	WARNING	Two assumptions asserting incompatible states

What UCIRS Does NOT Detect

• Bugs, CVEs, vulnerability severity
• Exploitability, performance regressions
• Correctness, safety, intent, "best practices"

One-line summary: UCIRS detects irreversible changes, assumption gaps, security exposure, and organizational decision patterns before context is lost.

---

CLI Commands

Command	Version	Description	Usage
ucirs install-hooks	v1	Install Git hooks in repo	Run in repo root
ucirs uninstall-hooks	v1	Remove Git hooks	Run in repo root
ucirs verify	v2	CI/PR verification (read-only)	Run in CI pipelines
ucirs replay <commit>	v2	Reconstruct enforcement state at commit	ucirs replay HEAD
ucirs incident [target]	v3	Cross-repo incident graph	ucirs incident
ucirs counterfactual <commit> --assumption=<id>	v5	Replay assumption dependencies	ucirs counterfactual HEAD --assumption=asm/123
ucirs github --pr=<num>	v5	Post read-only PR context comment	GITHUB_TOKEN=xxx ucirs github --pr=123
ucirs --version	v1	Show version
ucirs --help	v1	Show help

---

Library API

For programmatic use in Node.js:

const ucirs = require('ucirs');

// Core functions
ucirs.loadAssumptions(dir);         // Load assumptions from .ucirs/
ucirs.createAssumption({...});      // Create new assumption
ucirs.validateAssumption(obj);      // Validate assumption schema

// Irreversibility detection
ucirs.classifyByFilePath(path);     // Classify by file path
ucirs.classifyByContent(content);   // Classify by content

// Security (v4)
ucirs.classifySecurityRelevance(file, content);

// Meta-reasoning (v5)
ucirs.buildTopologyMap(assumptions);         // Assumption relationships
ucirs.compileEpistemicDebt(assumptions);     // Unresolved unknowns
ucirs.calculatePressureMetrics([], n1, n2);  // Irreversibility pressure
ucirs.detectBlindSpots(assumptions, []);     // Org blind spots
ucirs.detectConfidenceCascades(assumptions); // Repeated approvals
ucirs.generateSelfAwarenessMessage([]);      // UCIRS self-limits

---

VS Code Extension

Commands available:

• UCIRS: Show State — View enforcement mode and recent actions
• UCIRS: Declare Assumption — Create new assumption with context auto-fill
• UCIRS: Validate Assumptions — Check schema validity
• UCIRS: Analyze Current File — Check irreversibility classification
• UCIRS: Show Visibility Panel — Read-only view of assumptions and drift (v3+)
• UCIRS: Create Assumptions File — Generate template file

---

Version History

v1.0.0

Core enforcement: irreversibility detection, assumption requirements, Git hooks, VS Code integration.

v2.0.0

Lifecycle awareness: assumption aging/expiry, provenance tracking, incident replay, CI verification.

v3.0.0

Cross-repo coordination: linked assumptions, trust domains, ownership mapping, drift detection across repos.

v4.0.0

Security memory: security-critical classification, vulnerability context binding, security drift detection, decision pattern memory.

v5.0.0 (current)

Meta-reasoning: assumption topology mapping, counterfactual replay, confidence cascades, blind spots, epistemic debt, historical matching, GitHub PR integration.

See CHANGELOG.md for detailed changes.

---

Configuration

UCIRS uses .ucirs/state.json for local state (auto-generated, gitignored).

Enforcement modes:

• blocking (default): Block on violations
• advisory: Log violations, allow commit

---

Behavior Guarantees

Guarantee	Status
Silent when no irreversible actions detected	✓ Yes
Explains every block with remediation options	✓ Yes
Never modifies files without explicit action	✓ Yes
Degrades to advisory if state is corrupted	✓ Yes
Detects all possible irreversible patterns	✗ No
Validates assumption correctness	✗ No
Prevents all mistakes	✗ No

---

Contributing

This project follows these principles:

1. Accuracy over ambition
2. Clarity over cleverness
3. Explicit limits are required
4. No anthropomorphic verbs (knows, thinks, decides)
5. No safety guarantees

Pull requests must include tests and documentation updates.