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.