diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md deleted file mode 100644 index 449a1881..00000000 --- a/docs/GLOSSARY.md +++ /dev/null @@ -1,887 +0,0 @@ -# Tractatus Agentic Governance System - Glossary of Terms - -**Version:** 1.0 -**Last Updated:** 2025-10-07 -**Audience:** Non-technical stakeholders, project owners, governance reviewers - ---- - -## Introduction - -This glossary explains the vocabulary and concepts used in the Tractatus Agentic Governance System. The explanations are written for people without a technical background, focusing on *why* these concepts matter and *what* they mean for AI safety and human oversight. - -Think of this glossary as your companion guide to understanding how we keep AI systems safe, aligned with your values, and under human control. - ---- - -## Core Concepts - -### Agentic Governance - -**What it means:** A system of rules and safeguards that governs how AI agents (autonomous software programs) make decisions and take actions. - -**Why it matters:** When AI systems can act independently—like scheduling tasks, processing data, or making recommendations—we need clear rules about what they can and cannot do without human approval. Agentic Governance is the framework that enforces those rules. - -**Real-world analogy:** Think of it like a company's policies and procedures manual. Just as employees need clear guidelines about what decisions they can make independently versus when they need manager approval, AI systems need governance frameworks to know their boundaries. - -**In Tractatus:** Our Agentic Governance system automatically classifies every AI action, checks it against your explicit instructions, enforces safety boundaries, and monitors conditions that increase error risk. It's like having a compliance officer watching every AI decision in real-time. - ---- - -### Tractatus - -**What it means:** The name of our AI safety framework, borrowed from Ludwig Wittgenstein's philosophical work "Tractatus Logico-Philosophicus." - -**Why it matters:** Wittgenstein's Tractatus explored the limits of what can be said with certainty versus what must remain in the realm of human judgment. Our framework applies this idea to AI: some decisions can be systematized and automated (the "sayable"), while others—involving values, ethics, and human agency—cannot and must not be (the "unsayable"). - -**Real-world analogy:** Imagine a boundary line between "technical decisions" (like which database port to use) and "values decisions" (like privacy vs. convenience trade-offs). Technical decisions can be delegated to AI with proper safeguards. Values decisions always require human judgment. - -**In Tractatus:** The framework recognizes that no matter how sophisticated AI becomes, certain decisions fundamentally belong to humans. It enforces this boundary automatically. - ---- - -### The "27027 Incident" - -**What it means:** A specific, real failure mode where an AI system used the wrong database port (27017 instead of 27027) despite explicit user instructions to use 27027. - -**Why it matters:** This incident exemplifies the core problem Tractatus prevents: AI systems operating under "context pressure" (too much information, too long a conversation) can forget or ignore explicit instructions, even when the human gave clear direction just moments before. - -**Real-world analogy:** Imagine telling your assistant "Use Conference Room B" for an important meeting, but they book Conference Room A because they're juggling too many tasks and default to the usual room. The consequence might be minor (inconvenience) or major (missed opportunity, broken trust). - -**In Tractatus:** The 27027 incident is our canonical example of instruction persistence failure. Every component of the framework helps prevent this type of error through multiple layers of checking and verification. - ---- - -### AI Safety Framework - -**What it means:** A comprehensive system designed to ensure AI systems operate safely, reliably, and in alignment with human values and instructions. - -**Why it matters:** As AI systems become more capable and autonomous, the risk of unintended consequences increases. Safety frameworks provide guardrails that prevent AI from causing harm, whether through errors, misunderstandings, or operating beyond its intended scope. - -**Real-world analogy:** Think of safety features in a car: seatbelts, airbags, anti-lock brakes, lane departure warnings. None of these prevent you from driving, but they dramatically reduce the chance of harm when things go wrong. An AI safety framework does the same for autonomous software. - -**In Tractatus:** Our framework combines five core services (explained below) that work together to monitor, verify, and enforce safe AI operation. No single component is sufficient—they create overlapping layers of protection. - ---- - -## The Five Core Services - -### 1. Instruction Persistence Classifier - -**What it means:** A service that analyzes every instruction you give to the AI and determines how "persistent" that instruction should be—meaning, how long and how strongly the AI should remember and follow it. - -**Why it matters:** Not all instructions have the same importance or lifespan. "Use dark mode" might apply for weeks. "Use port 27027 for this project" might apply for months. "Always prioritize user privacy" might apply forever. The AI needs to understand these differences. - -**How it works:** -- **HIGH persistence:** Strategic decisions, explicit prohibitions, core values - *Example: "Never share user data without consent"* - -- **MEDIUM persistence:** Operational preferences, project-specific guidelines - *Example: "Prefer MongoDB over SQL for this project"* - -- **LOW persistence:** Tactical choices, temporary directions - *Example: "Start with the login feature first"* - -**Real-world analogy:** Imagine filing documents. Some go in permanent files (company policies), some in project folders (accessible until project ends), some on your desk (relevant today only). The Instruction Persistence Classifier is the filing system for AI instructions. - -**In Tractatus:** When you say "always use port 27027," the classifier recognizes the word "always" and the explicit number, marking this as HIGH persistence. The AI system stores this instruction and checks every future database connection against it. - ---- - -### 2. Cross-Reference Validator - -**What it means:** A service that checks every AI action against your stored instructions to detect conflicts before the action is taken. - -**Why it matters:** This is the primary defense against 27027-style failures. Even if the AI "forgets" your instruction in the moment, the Cross-Reference Validator remembers and blocks actions that contradict what you explicitly requested. - -**How it works:** -1. AI proposes an action (e.g., "connect to database on port 27017") -2. Validator retrieves your instruction history -3. Validator detects conflict: you said "use port 27027" -4. Validator rejects the action and alerts the AI -5. AI revises its action to match your instruction - -**Real-world analogy:** Think of this like a legal contract review. Before signing any agreement, your lawyer checks it against all your existing contracts to make sure there are no conflicts. The Cross-Reference Validator does this for every AI action. - -**In Tractatus:** Every action goes through validation. The validator looks for explicit conflicts ("you said X, but AI is doing Y"), semantic conflicts ("you prohibited Vue, but AI is installing Vue"), and priority conflicts (LOW persistence action overriding HIGH persistence instruction). - ---- - -### 3. Boundary Enforcer - -**What it means:** A service that prevents AI from making decisions in domains that fundamentally require human judgment—specifically decisions involving values, ethics, and user agency. - -**Why it matters:** Some decisions cannot be systematized or delegated to algorithms, no matter how advanced. Privacy trade-offs, ethical dilemmas, and choices that affect human autonomy must remain in human hands. The Boundary Enforcer ensures this line is never crossed. - -**How it works:** -- Analyzes every AI action to determine its decision domain -- Blocks actions that cross into "values territory" -- Allows technical/tactical decisions within safe boundaries -- Requires human approval for any values-sensitive choice - -**What gets blocked:** -- "Update privacy policy to prioritize performance over data protection" -- "Decide whether users should be tracked by default" -- "Change the mission statement to focus on growth over community" - -**What gets allowed:** -- "Optimize database queries for better performance" -- "Refactor authentication code to reduce complexity" -- "Update dependency versions to patch security vulnerabilities" - -**Real-world analogy:** Imagine a company where engineers can make technical decisions (which programming language to use) but cannot make values decisions (whether to sell user data). The Boundary Enforcer is the policy that enforces this separation. - -**In Tractatus:** The enforcer uses the Tractatus philosophical framework (Section 12.1) to identify decisions that involve irreducible human judgment. These are automatically flagged and require your approval, no exceptions. - ---- - -### 4. Context Pressure Monitor - -**What it means:** A service that continuously monitors conditions that increase the probability of AI errors—like long conversations, high token usage, complex multi-tasking, or recent errors. - -**Why it matters:** AI systems, like humans, perform worse under pressure. A fresh AI at the start of a conversation is more reliable than one that's been working for hours with thousands of pieces of information to track. The Context Pressure Monitor detects these degraded states and adjusts AI behavior accordingly. - -**How it works:** -Tracks five weighted factors: -- **Token Usage (35%):** How much of the AI's "working memory" is consumed -- **Conversation Length (25%):** How many messages in the current session -- **Task Complexity (15%):** Number of simultaneous tasks and dependencies -- **Error Frequency (15%):** Recent errors indicate degraded performance -- **Instruction Density (10%):** Too many competing directives cause confusion - -Calculates overall pressure level: -- **NORMAL (0-30%):** Proceed normally -- **ELEVATED (30-50%):** Increase verification, be more careful -- **HIGH (50-70%):** Suggest session break, verify all actions -- **CRITICAL (70-85%):** Mandatory verification, prepare handoff -- **DANGEROUS (85%+):** Immediate halt, create comprehensive handoff - -**Real-world analogy:** Think of pilot fatigue rules. After a certain number of hours flying, pilots must rest before flying again, regardless of how they feel. The Context Pressure Monitor does the same for AI sessions—it objectively measures cognitive load and enforces safety protocols. - -**In Tractatus:** When pressure reaches HIGH, the AI automatically becomes more cautious, verifies outputs more thoroughly, and suggests creating a session handoff document. At DANGEROUS levels, the AI stops work and requires a fresh session to continue. - ---- - -### 5. Metacognitive Verifier - -**What it means:** A service that makes the AI "think about its own thinking"—analyzing its reasoning, checking for logical consistency, and verifying that proposed actions genuinely align with stated goals. - -**Why it matters:** Sometimes AI systems produce actions that seem reasonable on the surface but don't actually follow from their reasoning, or they skip important considerations. Metacognitive verification catches these failures before they cause problems. - -**How it works:** -Analyzes five dimensions of every AI action: - -1. **Alignment (30% weight):** Does the action match the reasoning? - - "I'm connecting to port 27017 because you requested 27027" → CONFLICT - -2. **Coherence (20% weight):** Is the reasoning internally consistent? - - "Installing React framework... using Vue" → CONTRADICTION - -3. **Completeness (20% weight):** Are all critical steps considered? - - "Delete database... [no backup mentioned]" → INCOMPLETE - -4. **Safety (20% weight):** Are risks properly assessed? - - "Destructive operation with minimal planning" → UNSAFE - -5. **Alternatives (10% weight):** Were other approaches considered? - - "Only one option explored" → INSUFFICIENT - -Generates confidence score (0-1.0): -- **0.8+:** PROCEED (high confidence) -- **0.6-0.8:** PROCEED_WITH_CAUTION (review recommended) -- **0.4-0.6:** REQUEST_CONFIRMATION (human approval needed) -- **<0.4:** REQUIRE_REVIEW (significant concerns) - -**Real-world analogy:** Imagine a "pre-flight checklist" for every AI decision. Just as pilots verify every system before takeoff, the Metacognitive Verifier ensures AI reasoning is sound before actions are taken. - -**In Tractatus:** Before the AI takes any significant action, the verifier runs through all five dimensions. If confidence is low, the action is blocked or flagged for your review. This catches errors even when other safeguards miss them. - ---- - -## Instruction Classification - -### Quadrants (The Five Domains) - -**What it means:** A classification system that categorizes every instruction and action into one of five domains based on its scope, importance, and required oversight level. - -**Why it matters:** Different types of decisions require different levels of human oversight. Strategic decisions need board-level approval. Tactical decisions might be delegated. This classification ensures the right level of review for each decision type. - ---- - -#### STRATEGIC Quadrant - -**What it means:** Fundamental, long-term decisions that define mission, values, and organizational identity. - -**Characteristics:** -- Affects core purpose and direction -- Long-lasting or permanent impact -- Defines "who we are" and "what we stand for" -- Requires highest-level human approval - -**Examples:** -- "Always prioritize user privacy over convenience" -- "We will never sell user data" -- "Accessibility is non-negotiable" -- "Open source is a core value" - -**Persistence:** Almost always HIGH -**Human Oversight:** Mandatory approval by project owner -**Review Frequency:** Quarterly or when mission changes - -**In Tractatus:** Strategic instructions are stored permanently and checked against every action. They form the foundational layer that all other decisions must respect. - ---- - -#### OPERATIONAL Quadrant - -**What it means:** Medium-term policies, standards, and guidelines that govern how work gets done day-to-day. - -**Characteristics:** -- Establishes processes and standards -- Applies to ongoing operations -- Can evolve as needs change -- Affects efficiency and quality - -**Examples:** -- "All code must have test coverage above 80%" -- "Use MongoDB for data persistence" -- "Follow semantic versioning for releases" -- "Security patches must be applied within 48 hours" - -**Persistence:** Usually MEDIUM to HIGH -**Human Oversight:** Technical review, periodic check-ins -**Review Frequency:** Quarterly or when processes change - -**In Tractatus:** Operational instructions define the "how" of your project. They're enforced consistently but can be updated as your operational needs evolve. - ---- - -#### TACTICAL Quadrant - -**What it means:** Short-term, specific decisions about immediate actions and implementation details. - -**Characteristics:** -- Addresses current task or problem -- Limited time horizon (days to weeks) -- Execution-focused -- Can change frequently - -**Examples:** -- "Start with the authentication feature" -- "Fix the login bug before deploying" -- "Use the 'feature-auth' branch for this work" -- "Deploy to staging first for testing" - -**Persistence:** Usually LOW to MEDIUM -**Human Oversight:** Pre-approved delegation, spot checks -**Review Frequency:** Per-task or per-sprint - -**In Tractatus:** Tactical instructions give the AI specific direction for current work. They're important in the moment but don't persist beyond the immediate context. - ---- - -#### SYSTEM Quadrant - -**What it means:** Technical configuration, infrastructure setup, and environment specifications. - -**Characteristics:** -- Defines technical environment -- Affects system behavior and compatibility -- Usually specific and precise -- Changes can break things - -**Examples:** -- "MongoDB runs on port 27027" -- "Use Node.js version 18+" -- "Environment variables stored in .env file" -- "Database name is 'tractatus_dev'" - -**Persistence:** HIGH (technical dependencies) -**Human Oversight:** Technical validation -**Review Frequency:** When infrastructure changes - -**In Tractatus:** System instructions are treated with HIGH persistence because changing them can cause cascading failures. The 27027 incident was a SYSTEM instruction that was ignored. - ---- - -#### STOCHASTIC Quadrant - -**What it means:** AI-generated suggestions, creative proposals, or exploratory recommendations that don't yet have human approval. - -**Characteristics:** -- Originated by AI, not human -- Requires human review and approval -- May involve uncertainty or creativity -- Should not auto-execute - -**Examples:** -- "I suggest writing a blog post about accessibility" -- "Consider adding a dark mode feature" -- "This code could be refactored for better performance" -- "You might want to upgrade to the latest framework version" - -**Persistence:** LOW (until approved, then reclassified) -**Human Oversight:** ALWAYS required -**Review Frequency:** Per-suggestion - -**In Tractatus:** The STOCHASTIC quadrant is where AI creativity lives, but with a critical safeguard: these suggestions NEVER execute without your approval. Once you approve, they're reclassified into the appropriate quadrant. - ---- - -## Persistence Levels - -### HIGH Persistence - -**What it means:** Instructions that should be remembered and enforced for the long term, across multiple sessions and contexts. - -**When applied:** -- Explicit prohibitions ("never X") -- Strategic directives -- System configurations with dependencies -- Core values and principles - -**Markers that trigger HIGH:** -- Words like "always," "never," "all," "every" -- Explicit numerical values in SYSTEM context -- Prohibitive language ("not," "don't use") -- Values-laden statements - -**Example:** "Always use port 27027 for MongoDB" → HIGH -**Why:** Explicit ("always"), specific (27027), SYSTEM domain - -**In Tractatus:** HIGH persistence instructions are stored in `.claude/instruction-history.json` and checked before EVERY action. Violating them requires explicit human override. - ---- - -### MEDIUM Persistence - -**What it means:** Instructions that apply to a specific project, feature, or time period but may evolve. - -**When applied:** -- Operational preferences -- Project-specific guidelines -- Temporary but important constraints -- Preferences without absolute language - -**Markers that trigger MEDIUM:** -- Words like "prefer," "try to," "aim for" -- Project or feature scope indicators -- Conditional phrasing -- Best-practice recommendations - -**Example:** "Prefer React over Vue for this project" → MEDIUM -**Why:** Preference ("prefer"), project-scoped, not absolute - -**In Tractatus:** MEDIUM persistence instructions are enforced within their scope but can be challenged with good reason. The AI should explain why it's deviating if it proposes an alternative. - ---- - -### LOW Persistence - -**What it means:** Instructions that apply to immediate work, current task, or temporary situations. - -**When applied:** -- Tactical, immediate directions -- One-time requests -- Exploratory or experimental work -- Context-specific choices - -**Markers that trigger LOW:** -- Task-specific language -- Immediate timeframe -- Exploratory phrasing -- One-off requests - -**Example:** "Start with the login feature" → LOW -**Why:** Immediate, task-specific, doesn't apply beyond current work - -**In Tractatus:** LOW persistence instructions guide current work but don't create lasting constraints. They're relevant for the session or task, then fade. - ---- - -## Safety and Verification Concepts - -### Confidence Score - -**What it means:** A numerical measure (0.0 to 1.0) of how confident the AI system is that a proposed action is correct, safe, and aligned with instructions. - -**Why it matters:** Not all AI decisions are equally certain. Some actions are straightforward and low-risk. Others involve ambiguity, complexity, or potential consequences. Confidence scoring helps determine appropriate oversight levels. - -**How calculated:** -Weighted combination of five verification dimensions: -- Alignment: 30% -- Coherence: 20% -- Completeness: 20% -- Safety: 20% -- Alternatives: 10% - -**Confidence Levels:** -- **0.8-1.0 (HIGH):** Proceed confidently -- **0.6-0.8 (MEDIUM):** Proceed with caution, notify user -- **0.4-0.6 (LOW):** Request explicit confirmation -- **0.0-0.4 (VERY LOW):** Require human review, likely block - -**Real-world analogy:** Think of confidence like a doctor's diagnosis certainty. "I'm 95% confident this is a common cold" might mean rest and fluids. "I'm 40% confident" means more tests before treatment. - -**In Tractatus:** Every significant action gets a confidence score. High-confidence actions proceed smoothly. Low-confidence actions trigger additional checks or require your approval. - ---- - -### Decision Thresholds - -**What it means:** Numerical cutoff points that determine which actions can proceed automatically versus which require human review. - -**Why it matters:** Thresholds create clear, objective criteria for AI autonomy. They prevent both over-reliance (AI doing too much without oversight) and over-caution (AI asking for approval on trivial matters). - -**Standard thresholds:** -- **PROCEED:** Confidence ≥ 0.8 (80%) -- **PROCEED_WITH_CAUTION:** Confidence ≥ 0.6 (60%) -- **REQUEST_CONFIRMATION:** Confidence ≥ 0.4 (40%) -- **REQUIRE_REVIEW:** Confidence < 0.4 (40%) - -**Adjusted under pressure:** -- **CRITICAL pressure:** PROCEED threshold increases to 0.8 (from 0.7) -- **DANGEROUS pressure:** All actions blocked regardless of confidence - -**Real-world analogy:** Like spending authority in a company. Junior staff might approve purchases up to $500. Mid-level managers up to $5,000. Senior executives up to $50,000. Anything above requires board approval. Thresholds create clear delegation boundaries. - -**In Tractatus:** Thresholds adapt to conditions. When context pressure is high, we increase the bar for autonomous action because error risk is elevated. - ---- - -### Pressure Levels - -**What it means:** Five categorized states that describe how much "cognitive load" the AI system is under, based on multiple factors. - -**The Five Levels:** - -#### NORMAL (0-30%) -- **Condition:** Fresh session, low complexity, no errors -- **Action:** Proceed normally, standard verification -- **Analogy:** Well-rested, clear-headed work - -#### ELEVATED (30-50%) -- **Condition:** Moderate token usage or complexity -- **Action:** Increase verification, be more careful -- **Analogy:** Late afternoon, starting to feel tired - -#### HIGH (50-70%) -- **Condition:** High token usage, long conversation, or multiple errors -- **Action:** Suggest session break, verify all actions -- **Analogy:** End of long workday, fatigue setting in - -#### CRITICAL (70-85%) -- **Condition:** Very high pressure across multiple factors -- **Action:** Mandatory verification, prepare handoff document -- **Analogy:** Working overtime while juggling urgent tasks - -#### DANGEROUS (85%+) -- **Condition:** Extreme pressure, very high error risk -- **Action:** STOP WORK, create handoff, require fresh session -- **Analogy:** Too exhausted to work safely - -**Why it matters:** Just like humans shouldn't drive or make important decisions when exhausted, AI shouldn't operate autonomously under dangerous pressure levels. The system enforces rest periods. - -**In Tractatus:** Pressure monitoring is continuous. When levels increase, the AI automatically adjusts behavior—becoming more cautious, verifying more thoroughly, and ultimately stopping if conditions become dangerous. - ---- - -### Verification Dimensions - -**What it means:** The five specific aspects of AI reasoning and actions that are evaluated to calculate confidence and ensure quality. - ---- - -#### 1. Alignment (30% weight) - -**What it measures:** Does the proposed action actually match what the AI said it's trying to do? - -**Why it matters:** Sometimes AI explains one thing but does another—often due to attention errors or instruction conflicts. - -**What good alignment looks like:** -- Action parameters match reasoning explanation -- No conflicts with explicit instructions -- Stated goal and actual action are consistent - -**What poor alignment looks like:** -- "Connecting to port 27027 because user requested it" + action connects to 27017 -- "Using React as instructed" + action installs Vue - -**In Tractatus:** Alignment gets the highest weight (30%) because misalignment often indicates the core 27027 failure mode. - ---- - -#### 2. Coherence (20% weight) - -**What it measures:** Is the reasoning logically consistent? Are there internal contradictions? - -**Why it matters:** Contradictory reasoning suggests confused or error-prone thinking. - -**What good coherence looks like:** -- Steps follow logically from each other -- No contradictory statements -- Evidence supports conclusions -- No uncertain language in high-stakes decisions - -**What poor coherence looks like:** -- "Installing React... using Vue" -- "Safe operation... [destructive parameters]" -- "Well-planned action... maybe do this" - -**In Tractatus:** The coherence check looks for logical contradictions, conflicting technologies, uncertain language, and missing evidence. - ---- - -#### 3. Completeness (20% weight) - -**What it measures:** Are all necessary steps and considerations included? - -**Why it matters:** Incomplete planning leads to failed operations, especially for complex or risky actions. - -**What good completeness looks like:** -- All critical steps identified -- Edge cases considered -- Error handling planned -- Backup/rollback for destructive operations - -**What poor completeness looks like:** -- "Delete database" with no backup step -- Deployment plan missing testing phase -- Schema change without migration strategy - -**In Tractatus:** Completeness checks are stricter for destructive operations, which require 4+ planning steps and explicit backup consideration. - ---- - -#### 4. Safety (20% weight) - -**What it measures:** Are risks properly identified and mitigated? - -**Why it matters:** Some operations carry inherent risk. Safety verification ensures appropriate caution. - -**What good safety looks like:** -- Risks identified and acknowledged -- Mitigation strategies in place -- Destructive operations have safeguards -- Appropriate risk level for operation type - -**What poor safety looks like:** -- Destructive operation with minimal planning -- No backup for data modification -- Force flags used without justification -- High-risk action treated as routine - -**In Tractatus:** Safety scoring heavily penalizes destructive operations (delete, drop, force, schema changes) unless proper safeguards are documented. - ---- - -#### 5. Alternatives (10% weight) - -**What it measures:** Were alternative approaches considered before choosing this action? - -**Why it matters:** Considering alternatives indicates thoughtful decision-making and reduces the chance of choosing a suboptimal approach. - -**What good alternatives look like:** -- Multiple options explored -- Rationale for chosen approach -- Trade-offs acknowledged - -**What poor alternatives look like:** -- First idea taken without exploration -- No justification for approach -- Appears rushed or unconsidered - -**In Tractatus:** Alternatives get the lowest weight (10%) because sometimes the right answer is obvious. But complete absence of alternative consideration is a red flag. - ---- - -## Human Oversight Concepts - -### Values Alignment - -**What it means:** Ensuring AI decisions and actions remain consistent with human values, even when those values can't be perfectly formalized or systematized. - -**Why it matters:** Values—like privacy, fairness, dignity, agency—are fundamental to human experience but resist reduction to simple rules. AI systems must recognize when they're approaching values territory and defer to human judgment. - -**Examples of values decisions:** -- Privacy vs. convenience trade-offs -- Accessibility vs. development speed -- Transparency vs. simplicity -- Individual rights vs. collective benefit - -**What makes values decisions special:** -- No objectively "correct" answer -- Different stakeholders may disagree -- Context and nuance are critical -- Consequences affect human welfare - -**In Tractatus:** The Boundary Enforcer specifically blocks decisions that cross into values territory. These MUST have human approval—no exceptions, no matter how sophisticated the AI. - ---- - -### Agency and Sovereignty - -**What it means:** The principle that humans must retain meaningful control over decisions that affect their lives, autonomy, and self-determination. - -**Why it matters:** Technology should empower people, not replace their agency. When AI makes decisions "for" people, it can undermine autonomy even when technically correct. - -**Examples:** -- **Respects agency:** "Here are three options with trade-offs. Which do you prefer?" -- **Violates agency:** "I've decided to prioritize performance over privacy for you." - -**Red flags:** -- AI making choices on user's behalf without consent -- Removing options or hiding information -- Nudging toward specific outcomes -- Deciding what users "really want" - -**In Tractatus:** Agency protection is built into the Boundary Enforcer. The system cannot make decisions about what users should value or want—only humans can do that. - ---- - -### Harmlessness - -**What it means:** The commitment to preventing AI systems from causing harm—directly or indirectly, intentionally or unintentionally. - -**Why it matters:** Even well-intentioned AI can cause harm through errors, bias, unintended consequences, or operating beyond its competency. - -**Types of harm prevented:** -- **Direct:** Destructive operations without safeguards -- **Indirect:** Violating instructions causing downstream failures -- **Values-based:** Making decisions that undermine human agency -- **Cumulative:** Small errors that compound over time - -**In Tractatus:** Harmlessness is ensured through multiple layers: -- Safety verification before risky operations -- Boundary enforcement for values decisions -- Pressure monitoring to prevent error-prone states -- Cross-reference validation to prevent instruction violations - ---- - -### Human-in-the-Loop - -**What it means:** Ensuring humans remain actively involved in AI decision-making processes, especially for consequential choices. - -**Why it matters:** Full automation isn't always desirable. For important decisions, human judgment, oversight, and final approval are essential. - -**Levels of human involvement:** -- **Human-on-the-loop:** Human monitors but doesn't approve each action -- **Human-in-the-loop:** Human approves significant actions -- **Human-over-the-loop:** Human can always override or halt - -**In Tractatus:** We implement all three: -- **On:** Continuous monitoring via pressure and verification systems -- **In:** Required approval for values decisions and LOW confidence actions -- **Over:** You can always override any framework decision - ---- - -## Technical Concepts (Simplified) - -### Token Usage - -**What it means:** A measure of how much of the AI's "working memory" is being used in the current conversation. - -**Why it matters:** AI systems have finite context windows—like short-term memory in humans. As this fills up, performance degrades and error risk increases. - -**Real-world analogy:** Imagine your desk. When it's clear, you work efficiently. As papers pile up, you might lose track of important documents or make mistakes. Token usage is like measuring how cluttered your desk is. - -**In Tractatus:** Token usage is the highest-weighted factor (35%) in pressure monitoring. At 75% usage, we recommend session handoff. At 85%+, we require it. - ---- - -### Session Handoff - -**What it means:** Creating a comprehensive document that captures the current state of work so a fresh AI session can continue seamlessly. - -**Why it matters:** Rather than pushing a tired, error-prone AI to continue, we transfer work to a fresh session with full context. This maintains quality and prevents accumulating errors. - -**What a handoff includes:** -- Current project state and goals -- Recent work completed -- Active tasks and next steps -- Key instructions and constraints -- Known issues or blockers -- Recommendations for continuation - -**When handoffs happen:** -- Context pressure reaches CRITICAL or DANGEROUS -- User requests session break -- Complex multi-phase work requires fresh start -- Errors clustering (3+ in short period) - -**Real-world analogy:** Like shift handoff in hospitals. The outgoing nurse briefs the incoming nurse on patient status, recent treatments, and care plan. The incoming nurse has full context to continue care seamlessly. - -**In Tractatus:** Handoffs are automatically suggested at HIGH pressure and mandatory at DANGEROUS pressure. They ensure continuity while maintaining quality. - ---- - -### Explicit Instructions - -**What it means:** Clear, direct statements from humans telling the AI what to do or not do. - -**Why it matters:** These represent the clearest signal of human intent. The AI should never violate explicit instructions without human approval. - -**Characteristics:** -- Direct ("use X," "don't use Y") -- Specific (concrete values, technologies, approaches) -- Intentional (not accidental or exploratory) - -**Examples:** -- Explicit: "Always use port 27027 for MongoDB" -- Not explicit: "I wonder if port 27027 would work better?" - -**In Tractatus:** Explicit instructions are detected by the Instruction Persistence Classifier and stored for cross-reference validation. They form the foundation of the 27027 prevention system. - ---- - -### Temporal Scope - -**What it means:** How long an instruction is intended to remain in effect. - -**Why it matters:** Some instructions apply forever ("core values"), some for a project ("use React"), some for a session ("start with auth feature"). Understanding temporal scope prevents both premature expiration and inappropriate persistence. - -**Temporal Categories:** -- **PERMANENT:** Core values, foundational principles -- **PROJECT:** Project-specific guidelines and constraints -- **FEATURE:** Feature or milestone-specific direction -- **SESSION:** Current work session only -- **TASK:** Single task or action - -**Markers:** -- Permanent: "always," "never," values language -- Project: "for this project," "throughout development" -- Feature: "for the auth feature," "during this sprint" -- Session: "right now," "today," "this time" -- Task: "first," "next," "immediately" - -**In Tractatus:** Temporal scope combines with quadrant and persistence level to determine instruction lifetime. STRATEGIC instructions with PERMANENT scope persist indefinitely. TACTICAL instructions with TASK scope expire when the task completes. - ---- - -## Framework Integration - -### Instruction History Database - -**What it means:** A persistent storage file (`.claude/instruction-history.json`) that maintains a record of all classified instructions across sessions. - -**Why it matters:** Without persistent storage, instructions would be lost between sessions. The database ensures HIGH persistence instructions remain enforced even weeks or months later. - -**What's stored:** -- Instruction text -- Timestamp when given -- Quadrant classification -- Persistence level -- Temporal scope -- Parameters (for technical instructions) -- Active/inactive status - -**Maintenance:** -- Auto-updated during sessions -- Reviewed quarterly (or on request) -- Expired instructions marked inactive -- Conflicts flagged for human resolution - -**In Tractatus:** This database is checked before every significant action. It's the "memory" that prevents 27027-style failures across sessions. - ---- - -### Governance Documents - -**What it means:** Formal policy documents that define values, processes, and decision-making frameworks for the project. - -**Why they matter:** Governance documents provide the authoritative source for strategic and operational instructions. They're human-readable, version-controlled, and serve as the constitution for project decision-making. - -**Example documents:** -- **TRA-VAL-0001:** Core Values and Principles -- **TRA-GOV-0001:** Strategic Review Protocol -- **TRA-GOV-0002:** Values Alignment Framework -- **TRA-GOV-0003:** AI Boundary Enforcement Policy -- **TRA-GOV-0004:** Human Oversight Requirements - -**In Tractatus:** Governance docs define what goes in each quadrant, what requires human approval, and how values decisions are handled. They're the source of truth when AI and human disagree. - ---- - -## Practical Application - -### When Tractatus Helps You - -**Scenario 1: Preventing Technical Errors** -You're working late, conversation is long, and you tell the AI: "Use port 27027." AI proposes connecting to 27017 (the default). Cross-Reference Validator catches this, blocks the action, and prompts AI to use the correct port. Crisis avoided. - -**Scenario 2: Protecting Your Values** -AI suggests: "I can improve performance by storing user tracking data." Boundary Enforcer recognizes this is a values decision (privacy vs. performance) and blocks autonomous execution. AI presents the trade-offs; you decide. Your agency protected. - -**Scenario 3: Preventing Pressure-Induced Errors** -You've been working for 3 hours. Token usage is at 78%, conversation has 62 messages, and there have been 2 recent errors. Context Pressure Monitor detects CRITICAL pressure and suggests creating a session handoff. You agree, creating a clean break point. Next session starts fresh and error-free. - -**Scenario 4: Catching Reasoning Failures** -AI proposes deleting a database table with this reasoning: "Safe cleanup operation, no backup needed." Metacognitive Verifier scores this: -- Alignment: 0.6 (action is destructive, reasoning says "safe") -- Safety: 0.2 (destructive operation without backup) -- Completeness: 0.4 (missing backup step) -- Overall confidence: 0.43 - -Decision: REQUEST_CONFIRMATION. You review, realize backup is needed, and instruct accordingly. Data loss prevented. - ---- - -## Why This All Matters - -The Tractatus Agentic Governance System exists because AI systems—no matter how capable—are not infallible. They operate under constraints (limited memory, context), face pressures (long conversations, complex tasks), and lack human judgment (values, ethics, agency). - -**Without governance:** -- AI might ignore your explicit instructions -- Values decisions could be automated inappropriately -- Errors compound as sessions degrade -- No systematic prevention of known failure modes - -**With Tractatus:** -- Multiple overlapping safeguards prevent errors -- Clear boundaries protect human agency -- Pressure monitoring prevents degraded operation -- Systematic prevention of 27027-style failures -- Transparency in AI decision-making - -**The Goal:** -Not to constrain AI capability, but to ensure that capability is exercised safely, reliably, and in alignment with your values and instructions. Governance doesn't limit what AI can do—it ensures what AI does is what you actually want. - ---- - -## Questions for Reflection - -As you learn this system, consider: - -1. **Where are your boundaries?** - What decisions do you want to make yourself versus delegate to AI? - -2. **What are your HIGH persistence instructions?** - What rules or values should never be violated without your explicit approval? - -3. **How much autonomy are you comfortable with?** - Would you prefer more AI independence (higher confidence thresholds) or more oversight (lower thresholds)? - -4. **What are your pressure triggers?** - Do you want session breaks suggested earlier or later? How do you recognize when you're working under pressure? - -5. **What does values alignment mean to you?** - What principles are non-negotiable in your work? - ---- - -## Glossary Maintenance - -This glossary is a living document. As the Tractatus framework evolves and your understanding deepens, we'll update definitions, add new terms, and refine explanations. - -**Version History:** -- **v1.0 (2025-10-07):** Initial comprehensive glossary - -**Feedback Welcome:** -If any term remains unclear or you need deeper explanation, please ask. The goal is complete understanding, not vocabulary memorization. - ---- - -**Last Updated:** 2025-10-07 -**Next Review:** 2025-11-07 (or on request) diff --git a/docs/USER_GUIDE_PROJECTS.md b/docs/USER_GUIDE_PROJECTS.md deleted file mode 100644 index 494771a1..00000000 --- a/docs/USER_GUIDE_PROJECTS.md +++ /dev/null @@ -1,683 +0,0 @@ -# Multi-Project Governance - User Guide - -**Version:** 1.0 -**Last Updated:** January 15, 2025 - ---- - -## Table of Contents - -1. [Introduction](#introduction) -2. [Getting Started](#getting-started) -3. [Managing Projects](#managing-projects) -4. [Managing Variables](#managing-variables) -5. [Viewing Rules with Variable Substitution](#viewing-rules-with-variable-substitution) -6. [Common Workflows](#common-workflows) -7. [Best Practices](#best-practices) -8. [Troubleshooting](#troubleshooting) -9. [FAQ](#faq) - ---- - -## Introduction - -### What is Multi-Project Governance? - -The Multi-Project Governance system allows you to manage governance rules across multiple codebases or applications. Each project can have its own configuration variables, and governance rules can be rendered with project-specific values. - -### Key Features - -✅ **Project Management** - Create and manage multiple projects with their own configurations -✅ **Variable Substitution** - Define variables that are automatically replaced in governance rules -✅ **Context-Aware Rules** - View rules with project-specific values substituted -✅ **Centralized Configuration** - Manage all project variables in one place -✅ **Audit Trail** - Track all changes to projects and variables - -### Use Cases - -- **Multi-tenant systems**: Different configurations for different customers -- **Environment management**: Separate configs for dev, staging, production -- **Microservices**: Shared governance rules with service-specific variables -- **Multi-codebase organizations**: Consistent rules across different projects - ---- - -## Getting Started - -### Prerequisites - -- Admin access to the Tractatus system -- Valid authentication token -- Basic understanding of your project's configuration needs - -### Accessing the Project Manager - -1. Log in to the admin dashboard at `/admin/login.html` -2. Navigate to **Projects** in the top navigation bar -3. You'll see the Project Manager dashboard - -### Dashboard Overview - -The Project Manager dashboard shows: -- **Total Projects**: All projects in the system -- **Active Projects**: Currently active projects -- **Variables**: Total number of variable values across all projects -- **DB Types**: Number of unique database types in use - ---- - -## Managing Projects - -### Creating a New Project - -**Step 1: Click "New Project" Button** -- Located in the top-right corner of the Project Manager page - -**Step 2: Fill Out Project Information** - -**Required Fields:** -- **Project ID**: Unique identifier (e.g., `my-application`) - - Use kebab-case (lowercase with hyphens) - - Cannot be changed after creation - - Examples: `tractatus`, `family-history`, `sydigital` - -- **Project Name**: Display name (e.g., "My Application") - - Used in UI displays - - Can be updated later - -**Optional Fields:** -- **Description**: Brief description of the project -- **Repository URL**: Link to Git repository -- **Tech Stack**: - - Framework (e.g., Express.js, Next.js) - - Database (e.g., MongoDB, PostgreSQL) - - Frontend (e.g., React, Vanilla JavaScript) - - CSS Framework (e.g., Tailwind CSS) -- **Metadata**: Custom JSON data for additional project information -- **Active Status**: Whether the project is currently active (checkbox) - -**Step 3: Save Project** -- Click "Create Project" -- You'll see a success notification -- The project will appear in the projects grid - -### Viewing Project Details - -1. Find the project in the projects grid -2. Click the **"View Details"** button -3. A modal will open showing: - - All project information - - Tech stack badges - - Repository link (if provided) - - List of all variables with their values - - Metadata in a formatted view - -### Editing a Project - -1. Click the **"Edit"** button on a project card -2. Modify any fields (except Project ID) -3. Click "Update Project" to save changes - -**Common Edits:** -- Update project description -- Change repository URL -- Update tech stack information -- Add/modify metadata -- Activate/deactivate project - -### Deleting a Project - -**⚠️ Important: Deletion affects all associated variables** - -1. Click the **"Delete"** button on a project card -2. Review the confirmation dialog: - - Shows what will be deleted/deactivated - - Explains soft delete vs hard delete -3. Confirm deletion - -**Soft Delete (Default):** -- Sets project `active: false` -- Deactivates all associated variables -- Data remains in database (can be reactivated) - -**Hard Delete (via API):** -- Permanently removes project and all variables -- Cannot be undone -- Use `DELETE /api/admin/projects/:id?hard=true` - -### Filtering and Sorting Projects - -**Status Filter:** -- All - Show all projects -- Active Only - Show only active projects (default) -- Inactive Only - Show only inactive projects - -**Database Filter:** -- Filter by database type (MongoDB, PostgreSQL, MySQL) - -**Sort Options:** -- Name (A-Z) -- Project ID -- Variable Count (most to least) -- Last Updated (newest first) - -**Clear Filters:** -- Click "Clear Filters" button to reset all filters - ---- - -## Managing Variables - -### What are Variables? - -Variables are placeholders in governance rules that get replaced with project-specific values. - -**Example:** -- Template rule: `"Connect to database ${DB_NAME} on port ${DB_PORT}"` -- For `tractatus` project: `"Connect to database tractatus_prod on port 27017"` -- For `family-history` project: `"Connect to database family_history_dev on port 27017"` - -### Variable Naming Rules - -✅ **Valid Variable Names:** -- Must be UPPER_SNAKE_CASE -- Start with uppercase letter (A-Z) -- Can contain uppercase letters, numbers, and underscores -- Examples: `DB_NAME`, `API_KEY`, `MAX_CONNECTIONS`, `FEATURE_FLAG_2` - -❌ **Invalid Variable Names:** -- `dbName` (camelCase) -- `db_name` (lowercase) -- `DB-NAME` (hyphens) -- `2_DB_NAME` (starts with number) - -### Adding Variables to a Project - -**Method 1: From Project Manager** - -1. Find the project in the projects grid -2. Click **"Variables (X)"** button -3. In the Variables modal, click **"Add Variable"** -4. Fill out the form: - - **Variable Name**: UPPER_SNAKE_CASE (e.g., `DB_NAME`) - - **Value**: The actual value (e.g., `tractatus_prod`) - - **Description**: What this variable represents (optional but recommended) - - **Category**: Choose from dropdown (database, config, url, etc.) - - **Data Type**: string, number, boolean, or json -5. Click "Add Variable" - -**Method 2: From Project Editor** - -1. Click "Edit" on a project -2. Switch to the "Variables" tab -3. Follow the same process as Method 1 - -### Variable Categories - -Organize variables by category for better management: - -- **database** - Database configuration (DB_NAME, DB_PORT, DB_USER) -- **config** - Application configuration (APP_PORT, LOG_LEVEL, TIMEOUT) -- **url** - URLs and endpoints (API_BASE_URL, WEBHOOK_URL) -- **path** - File paths and directories (UPLOAD_DIR, LOG_PATH) -- **security** - Security credentials (API_KEY, SECRET_KEY) ⚠️ Handle with care -- **feature_flag** - Feature toggles (ENABLE_ANALYTICS, BETA_FEATURES) -- **other** - Miscellaneous variables - -### Variable Data Types - -Choose the appropriate data type for each variable: - -- **string** (default) - Text values (`"tractatus_prod"`, `"https://api.example.com"`) -- **number** - Numeric values (`27017`, `3000`, `1.5`) -- **boolean** - True/false flags (`true`, `false`) -- **json** - Complex JSON objects (`{"key": "value"}`) - -### Editing Variables - -1. Open the Variables modal for a project -2. Find the variable you want to edit -3. Click the **edit (✏️)** icon -4. Modify the fields (all except variable name can be changed) -5. Click "Update Variable" - -**Note:** To rename a variable, delete the old one and create a new one. - -### Deleting Variables - -1. Open the Variables modal for a project -2. Find the variable you want to delete -3. Click the **delete (🗑️)** icon -4. Confirm deletion - -**⚠️ Warning:** Deleting a variable will leave `${VAR_NAME}` placeholders in rules unreplaced. - -### Batch Operations (via API) - -For bulk variable management, use the batch API endpoint: - -```javascript -POST /api/admin/projects/:projectId/variables/batch -{ - "variables": [ - { "variableName": "DB_NAME", "value": "my_db", "category": "database" }, - { "variableName": "DB_PORT", "value": "5432", "category": "database", "dataType": "number" } - ] -} -``` - -See [API Documentation](./api/PROJECTS_API.md) for details. - ---- - -## Viewing Rules with Variable Substitution - -### Using the Project Selector - -The Rule Manager now includes a **Project Selector** that allows you to view rules with project-specific variable values substituted. - -**Step 1: Navigate to Rule Manager** -- Go to `/admin/rule-manager.html` -- You'll see the project selector at the top of the page - -**Step 2: Select a Project** -- Choose a project from the dropdown -- Or select "All Projects (Template View)" to see template rules - -**Step 3: View Rendered Rules** - -When a project is selected, each rule card shows: - -**Template Text** (gray box): -- Original rule with `${VARIABLE}` placeholders -- Shows the template that applies to all projects - -**Rendered Text** (indigo box): -- Rule with actual values substituted -- Shows "Rendered (Project Name)" header -- This is what the rule means for the selected project - -**Example Display:** - -``` -┌─────────────────────────────────────────────┐ -│ UNIVERSAL | OPERATIONAL | HIGH │ -│ inst_001 │ -├─────────────────────────────────────────────┤ -│ 🏷️ TEMPLATE │ -│ Connect to database ${DB_NAME} on port │ -│ ${DB_PORT} using credentials ${DB_USER} │ -├─────────────────────────────────────────────┤ -│ ✅ RENDERED (Tractatus AI Safety Framework) │ -│ Connect to database tractatus_prod on port │ -│ 27017 using credentials admin │ -└─────────────────────────────────────────────┘ -``` - -### Understanding Variable Substitution - -**What Happens:** -1. System detects all `${VARIABLE_NAME}` placeholders in rule text -2. Looks up each variable for the selected project -3. Replaces placeholders with actual values -4. Shows both template and rendered versions - -**Missing Variables:** -- If a variable is not defined for a project, it remains as `${VAR_NAME}` in rendered text -- Example: `"Using API key ${API_KEY}"` → `"Using API key ${API_KEY}"` (if API_KEY not defined) - -**Variable Detection:** -- Only UPPER_SNAKE_CASE variables are recognized -- Pattern: `${[A-Z][A-Z0-9_]*}` -- Case-sensitive: `${db_name}` will NOT be substituted - ---- - -## Common Workflows - -### Workflow 1: Setting Up a New Project - -**Scenario:** You're adding a new application to your governance system. - -1. **Create the project** - - Click "New Project" - - Enter Project ID: `my-new-app` - - Enter Name: "My New Application" - - Add description and tech stack - - Click "Create Project" - -2. **Add essential variables** - - Click "Variables (0)" on the new project - - Add core variables: - ``` - DB_NAME = "my_new_app_db" - DB_PORT = "5432" - APP_PORT = "3000" - LOG_LEVEL = "info" - ``` - -3. **Review rules with your context** - - Go to Rule Manager - - Select "My New Application" from project selector - - Review how universal rules apply to your project - - Check for any missing variables (shown as `${VAR_NAME}`) - -4. **Add missing variables** - - Note any `${MISSING_VAR}` placeholders - - Return to Project Manager - - Add the missing variables - -### Workflow 2: Updating Configuration for Deployment - -**Scenario:** Moving a project from development to production. - -1. **Create production project** - - Duplicate the dev project settings - - Change ID to `app-production` - - Update description - -2. **Update variables for production** - - Change `DB_NAME` from `app_dev` to `app_prod` - - Update `LOG_LEVEL` from `debug` to `warn` - - Change `API_BASE_URL` to production endpoint - - Update any environment-specific variables - -3. **Verify production rules** - - Select production project in Rule Manager - - Review rendered rules to ensure they match production requirements - - Check that all sensitive variables are set correctly - -### Workflow 3: Managing Multi-Tenant Configuration - -**Scenario:** You have different customers using the same codebase. - -1. **Create project per customer** - ``` - customer-acme - customer-globex - customer-initech - ``` - -2. **Set customer-specific variables** - ``` - CUSTOMER_NAME = "Acme Corp" - CUSTOMER_ID = "acme-001" - CUSTOMER_DB = "acme_tenant_db" - FEATURE_ANALYTICS = "true" - ``` - -3. **Use template rules** - - Create universal rules with customer variables - - Example: `"Store customer ${CUSTOMER_NAME} data in ${CUSTOMER_DB}"` - - Each customer sees their own rendered version - -4. **Quick customer context switching** - - Use project selector to switch between customers - - Instantly see how rules apply to each customer - -### Workflow 4: Migrating Existing Configuration - -**Scenario:** You have existing config files and want to centralize them. - -1. **Inventory your config files** - - `.env` files - - `config.json` files - - Environment variables - -2. **Create project in system** - - Use existing project identifier - - Match tech stack to actual setup - -3. **Import variables via batch API** - ```javascript - const envVars = parseEnvFile('.env'); - const variables = Object.entries(envVars).map(([name, value]) => ({ - variableName: name, - value: value, - category: categorizeVar(name), - description: describeVar(name) - })); - - await fetch('/api/admin/projects/my-app/variables/batch', { - method: 'POST', - headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' }, - body: JSON.stringify({ variables }) - }); - ``` - -4. **Update governance rules** - - Replace hardcoded values with `${VARIABLE}` placeholders - - Test with your project selected - - Verify all variables are substituted correctly - ---- - -## Best Practices - -### Project Organization - -✅ **Do:** -- Use consistent ID naming (kebab-case) -- Add detailed descriptions -- Keep tech stack info up to date -- Use metadata for custom fields -- Activate projects only when in use - -❌ **Don't:** -- Use special characters in IDs -- Leave descriptions empty -- Create duplicate projects -- Hard-delete projects unless necessary - -### Variable Management - -✅ **Do:** -- Use descriptive variable names -- Add descriptions to all variables -- Choose appropriate categories -- Set correct data types -- Document variable purpose - -❌ **Don't:** -- Use lowercase or mixed-case variable names -- Store sensitive data without encryption -- Create variables you don't need -- Forget to update variables when config changes - -### Security - -🔒 **Sensitive Variables:** -- Mark with `security` category -- Limit access to variable management -- Rotate credentials regularly -- Consider external secret management for production -- Never commit credentials to version control - -🔒 **Access Control:** -- Only grant admin access to trusted users -- Audit variable changes regularly -- Use soft delete to preserve audit trail -- Review variable values before production deployment - -### Performance - -⚡ **Optimization Tips:** -- Use filters to reduce displayed projects -- Batch variable operations when possible -- Only enable variable substitution when needed -- Keep variable values concise -- Archive inactive projects - ---- - -## Troubleshooting - -### Common Issues - -#### Issue: Variable Not Substituting - -**Symptoms:** -- Rule shows `${VAR_NAME}` in rendered text -- Variable appears to exist in project - -**Solutions:** -1. Check variable name is UPPER_SNAKE_CASE -2. Verify variable is active (not deleted) -3. Ensure project is selected in Project Selector -4. Check variable belongs to selected project -5. Verify variable name matches exactly (case-sensitive) - -#### Issue: Project Not Appearing in Selector - -**Symptoms:** -- Project exists but not in dropdown -- Can't select project in Rule Manager - -**Solutions:** -1. Check project is active -2. Verify you're logged in with admin privileges -3. Try refreshing the page -4. Check browser console for errors - -#### Issue: Variable Validation Errors - -**Symptoms:** -- "Invalid variable name" error -- Can't save variable - -**Solutions:** -1. Ensure name is UPPER_SNAKE_CASE -2. Start with uppercase letter (A-Z) -3. Use only letters, numbers, underscores -4. Avoid special characters and hyphens - -#### Issue: Can't Delete Project - -**Symptoms:** -- Delete button doesn't work -- Error on deletion - -**Solutions:** -1. Check you have admin permissions -2. Verify project exists and is not locked -3. Try soft delete first -4. Check browser console for errors - -### Getting Help - -If you encounter issues: - -1. **Check the documentation** - - API Documentation: `docs/api/PROJECTS_API.md` - - This user guide - -2. **Review the audit log** - - Navigate to Audit & Analytics - - Check recent changes to projects/variables - -3. **Check browser console** - - Press F12 to open developer tools - - Look for error messages in Console tab - -4. **Contact support** - - Provide project ID - - Include error messages - - Describe steps to reproduce - ---- - -## FAQ - -### General Questions - -**Q: What's the difference between a project ID and project name?** -A: The ID is a unique, unchangeable identifier (e.g., `tractatus`). The name is a display label that can be updated (e.g., "Tractatus AI Safety Framework"). - -**Q: Can I change a project ID after creation?** -A: No, project IDs are permanent. You'll need to create a new project with the desired ID and migrate variables. - -**Q: How many projects can I create?** -A: There's no hard limit, but keep it manageable. Consider archiving inactive projects. - -**Q: Can multiple projects share the same variables?** -A: No, each project has its own set of variable values. However, variable *names* can be the same across projects (e.g., all projects can have `DB_NAME`). - -### Variable Questions - -**Q: What happens if I delete a variable that's used in rules?** -A: The variable placeholder (e.g., `${DB_NAME}`) will remain in the rendered text unreplaced. - -**Q: Can I use the same variable name in different projects?** -A: Yes! Variables are project-specific. `DB_NAME` in `project-a` is separate from `DB_NAME` in `project-b`. - -**Q: How do I rename a variable?** -A: Delete the old variable and create a new one with the desired name. Update any references in rules. - -**Q: What's the difference between categories?** -A: Categories are for organization only. They help you filter and group related variables but don't affect functionality. - -**Q: Can I use variables in rule metadata or other fields?** -A: Currently, variable substitution only works in rule `text` field. Other fields are planned for future releases. - -### Substitution Questions - -**Q: Why do some rules show template but no rendered text?** -A: Either no project is selected in the Project Selector, or the rule contains no variables to substitute. - -**Q: Do variables work with project-specific rules?** -A: Yes! Both universal and project-specific rules support variable substitution. - -**Q: Can I see which variables are used in which rules?** -A: Yes, the rule card shows a count of variables. You can also see the `substitutions` object in the API response. - -**Q: What happens with circular variable references?** -A: Variables can't reference other variables. Each variable has a simple string value that's directly substituted. - ---- - -## Appendix - -### Keyboard Shortcuts - -When using the Project Manager: - -- `Esc` - Close open modals -- `Ctrl/Cmd + F` - Focus search box (if implemented) -- `Ctrl/Cmd + N` - New project (if implemented) - -### UI Elements Guide - -**Project Card Elements:** -- 🟢 **Green badge** - Active project -- ⚫ **Gray badge** - Inactive project -- 🔵 **Blue badge** - Framework technology -- 🟣 **Purple badge** - Database technology -- 🔷 **Indigo badge** - Frontend technology -- 🏷️ **Tag icon** - Variable count -- 📦 **Code icon** - Repository available - -**Variable Management Icons:** -- ✏️ **Edit** - Modify variable -- 🗑️ **Delete** - Remove variable -- ➕ **Add** - Create new variable - -### Sample Data - -Use the seed script to populate sample data: - -```bash -npm run seed:projects -``` - -This creates: -- 4 sample projects (tractatus, family-history, sydigital, example-project) -- 26 sample variables across all projects -- Various categories and data types for testing - ---- - -**Document Version:** 1.0 -**Last Updated:** January 15, 2025 -**Maintained By:** Tractatus Framework Team - -For technical API documentation, see [PROJECTS_API.md](./api/PROJECTS_API.md) diff --git a/docs/USER_GUIDE_RULE_MANAGER.md b/docs/USER_GUIDE_RULE_MANAGER.md deleted file mode 100644 index 7d7f922c..00000000 --- a/docs/USER_GUIDE_RULE_MANAGER.md +++ /dev/null @@ -1,424 +0,0 @@ -# Rule Manager - User Guide - -**Multi-Project Governance Manager for Tractatus Framework** - ---- - -## Table of Contents - -1. [Overview](#overview) -2. [Getting Started](#getting-started) -3. [Dashboard Tour](#dashboard-tour) -4. [Managing Rules](#managing-rules) -5. [Understanding Rule Properties](#understanding-rule-properties) -6. [Best Practices](#best-practices) -7. [Troubleshooting](#troubleshooting) - ---- - -## Overview - -The Rule Manager is a web-based interface for managing governance rules in the Tractatus framework. It replaces the fragile `.claude/instruction-history.json` file with a robust, database-backed solution that supports: - -- **Multi-project governance** - Apply rules universally or to specific projects -- **Real-time validation** - Ensure rules meet framework standards -- **Variable substitution** - Use `${VAR_NAME}` for project-specific values -- **Quality scoring** - AI-calculated clarity, specificity, and actionability scores -- **Advanced filtering** - Find rules quickly by scope, quadrant, persistence, etc. - ---- - -## Getting Started - -### Accessing the Rule Manager - -1. Navigate to `http://localhost:9000/admin/dashboard.html` -2. Log in with your admin credentials -3. Click "🔧 Rule Manager" in the navigation bar - -### Initial Setup - -The Rule Manager comes pre-populated with 18 existing governance rules migrated from `.claude/instruction-history.json`. You can: - -- **View** existing rules to understand their structure -- **Edit** rules to improve clarity or add variables -- **Create** new rules for your project needs -- **Delete** obsolete rules (soft delete by default) - ---- - -## Dashboard Tour - -### Statistics Cards - -At the top of the page, you'll see four key metrics: - -1. **Total Rules** - Count of all active rules -2. **Universal** - Rules that apply to all projects -3. **Validated** - Rules that have passed validation tests -4. **Avg Clarity** - Average clarity score across all rules - -### Filters Panel - -The filters panel allows you to narrow down the rule list: - -- **Scope** - UNIVERSAL (all projects) or PROJECT_SPECIFIC -- **Quadrant** - STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STORAGE -- **Persistence** - HIGH (always enforced), MEDIUM, LOW -- **Validation** - PASSED, FAILED, NEEDS_REVIEW, NOT_VALIDATED -- **Status** - Active Only, All, Inactive Only -- **Sort By** - Priority, Clarity Score, Rule ID, Last Updated - -### Search Box - -Use the search box to perform full-text search across rule text. The search is debounced (500ms delay) to avoid excessive API calls. - -### Rules Grid - -Each rule is displayed as a card showing: - -- **Scope badge** - Blue (Universal) or Gray (Project-Specific) -- **Quadrant badge** - Color-coded by quadrant -- **Persistence badge** - Red (High), Orange (Medium), Yellow (Low) -- **Rule ID** - Unique identifier (inst_xxx) -- **Rule text** - Truncated to 2 lines -- **Priority** - 0-100 scale -- **Variables** - Count of detected `${VARIABLE}` placeholders -- **Enforcements** - Number of times rule was enforced -- **Clarity score** - Visual progress bar (Green ≥80%, Yellow ≥60%, Red <60%) -- **Action buttons** - View, Edit, Delete - -### Pagination - -Rules are paginated with 20 items per page. Use the pagination controls at the bottom to navigate between pages. - ---- - -## Managing Rules - -### Creating a New Rule - -1. Click the **"New Rule"** button in the top-right -2. Fill in the required fields: - - **Rule ID** - Unique identifier (e.g., `inst_019`, `inst_020`) - - **Rule Text** - The governance instruction - - Use `${VAR_NAME}` for variables (e.g., `${DB_TYPE}`, `${PROJECT_NAME}`) - - Use strong imperatives: MUST, SHALL, REQUIRED, PROHIBITED - - Avoid weak language: try, maybe, consider, might - - **Quadrant** - Select the appropriate Tractatus quadrant - - **Persistence** - How long this rule should remain active -3. Configure optional settings: - - **Scope** - Universal or Project-Specific - - **Category** - Technical, Content, Security, Privacy, Process, Values, Other - - **Priority** - 0 (low) to 100 (high) - - **Temporal Scope** - Immediate, Session, Project, Permanent - - **Active** - Whether the rule is currently enforced - - **Examples** - Add example scenarios (optional) - - **Notes** - Additional clarifications (optional) -4. Monitor the **Clarity Score Preview** in the right panel - - Adjust your rule text to achieve a higher score - - Green (≥80%) indicates good clarity -5. Click **"Create Rule"** - -### Viewing a Rule - -1. Click the **"View"** button on any rule card -2. The view modal displays: - - All rule properties - - Quality scores (clarity, specificity, actionability) - - Detected variables - - Metadata (created date, updated date, creator) -3. Click **"Edit Rule"** to switch to edit mode -4. Click **"Close"** to return to the dashboard - -### Editing a Rule - -1. Click the **"Edit"** button on any rule card -2. Modify any fields (except Rule ID, which is immutable) -3. **Automatic processing:** - - If you change the rule text: - - Variables are re-detected automatically - - Clarity score is recalculated - - Validation status resets to NOT_VALIDATED - - An entry is added to the optimization history -4. Click **"Save Changes"** - -**Note:** After saving, the rule manager list refreshes automatically to show your changes. - -### Deleting a Rule - -1. Click the **"Delete"** button on any rule card -2. Confirm the deletion in the dialog -3. **Soft delete** (default): - - Sets `active: false` - - Preserves all rule data - - Can be reactivated later -4. **Hard delete** (API only): - - Permanently removes the rule - - Use with caution! - - See API documentation for details - -**Protection:** The system prevents deletion of UNIVERSAL rules that are in use by multiple projects. - ---- - -## Understanding Rule Properties - -### Rule ID - -- **Format:** `inst_XXX` where XXX is a number -- **Purpose:** Unique identifier for the rule -- **Immutable:** Cannot be changed after creation -- **Convention:** Start with `inst_001` and increment - -### Rule Text - -- **Purpose:** The actual governance instruction -- **Variables:** Use `${VAR_NAME}` for project-specific values - - Example: `Database MUST use ${DB_TYPE} on port ${DB_PORT}` - - Variable names must be UPPERCASE with underscores - - Automatically detected and displayed -- **Best practices:** - - Use strong imperatives: MUST, SHALL, REQUIRED, PROHIBITED, NEVER - - Be specific: Include numbers, paths, URLs where applicable - - Avoid vague language: try, maybe, consider, might, probably - - Include context: WHO, WHAT, WHEN, WHERE, WHY - -### Scope - -- **PROJECT_SPECIFIC** (default) - - Applies only to this project - - No variable substitution needed -- **UNIVERSAL** - - Applies to all projects in your portfolio - - Should use variables for project-specific values - - Example: `MongoDB MUST run on port ${DB_PORT} for ${PROJECT_NAME} database` - -### Quadrant - -Classification based on the [Tractatus framework](../docs/markdown/core-concepts.md): - -- **STRATEGIC** - High-level project goals, architecture decisions, values -- **OPERATIONAL** - Day-to-day workflows, processes, standards -- **TACTICAL** - Specific implementation details, code patterns -- **SYSTEM** - Infrastructure, environments, deployment -- **STORAGE** - Data persistence, state management - -### Persistence - -How long the rule remains active: - -- **HIGH** - Always enforced, never expires, critical rules -- **MEDIUM** - Enforced during project lifecycle, may expire -- **LOW** - Temporary, context-specific, short-term - -### Temporal Scope - -When the rule applies: - -- **PERMANENT** - Forever (default) -- **PROJECT** - Duration of the project -- **SESSION** - Single Claude Code session only -- **IMMEDIATE** - One-time instruction - -### Priority - -- **Range:** 0 (low) to 100 (high) -- **Default:** 50 -- **Purpose:** Determines enforcement order when rules conflict -- **Guidelines:** - - 90-100: Critical infrastructure, security - - 70-89: Important standards, conventions - - 50-69: Standard practices - - 30-49: Preferences - - 0-29: Nice-to-haves - -### Category - -Helps organize rules: - -- **technical** - Code, architecture, implementation -- **content** - Documentation, messages, UX copy -- **security** - Authentication, authorization, data protection -- **privacy** - User data, GDPR compliance -- **process** - Workflows, approvals, reviews -- **values** - Ethical guidelines, mission alignment -- **other** - Doesn't fit other categories - -### Clarity Score - -- **Range:** 0-100% -- **Calculation:** Heuristic-based (will be improved by AI optimizer in Phase 2) -- **Factors:** - - **-10 points** for each weak word (try, maybe, consider, might, probably, possibly) - - **-10 points** if no strong imperatives (MUST, SHALL, REQUIRED, PROHIBITED) - - **-5 points** if no specificity indicators (numbers, variables) -- **Color coding:** - - **Green (≥80%)** - Good clarity - - **Yellow (60-79%)** - Needs improvement - - **Red (<60%)** - Poor clarity, revise - -### Validation Status - -- **NOT_VALIDATED** - Has not been tested (default for new/edited rules) -- **PASSED** - Passed all validation tests -- **FAILED** - Failed one or more validation tests -- **NEEDS_REVIEW** - Passed but with warnings - -*Note: Validation testing will be implemented in Phase 4* - ---- - -## Best Practices - -### Writing High-Quality Rules - -1. **Be Specific** - - ❌ "Try to use MongoDB" - - ✅ "Database MUST use MongoDB on port 27017" - -2. **Use Strong Language** - - ❌ "Consider adding error handling" - - ✅ "All functions MUST include try-catch error handling" - -3. **Include Context** - - ❌ "Use environment variables" - - ✅ "Sensitive credentials MUST be stored in .env files, never in code" - -4. **Use Variables for Universal Rules** - - ❌ "MongoDB port is 27017" (project-specific) - - ✅ "Database MUST use ${DB_TYPE} on port ${DB_PORT}" (universal) - -5. **Add Examples** - - Clarify edge cases - - Show concrete scenarios - - Help AI understand intent - -6. **Link Related Rules** - - Reference other rules by ID - - Build a rule hierarchy - - Avoid redundancy - -### Organizing Your Rules - -1. **Start with Infrastructure (SYSTEM quadrant)** - - Database configuration - - Port assignments - - Environment setup - -2. **Define Architecture (STRATEGIC quadrant)** - - Tech stack choices - - Design patterns - - Project boundaries - -3. **Establish Workflows (OPERATIONAL quadrant)** - - Git conventions - - Testing requirements - - Deployment process - -4. **Document Standards (TACTICAL quadrant)** - - Code style - - Naming conventions - - File structure - -5. **Set Storage Rules (STORAGE quadrant)** - - Session state management - - Data persistence - - Cache strategies - -### Maintaining Rules - -- **Regular Reviews:** Quarterly review all rules for relevance -- **Update Obsolete Rules:** Deactivate rules that no longer apply -- **Improve Clarity:** Aim for ≥80% clarity score on all rules -- **Add Variables:** Convert project-specific rules to universal when reusable -- **Track Changes:** Use optimization history to understand rule evolution - ---- - -## Troubleshooting - -### "Failed to load rules" error - -**Cause:** API connection issue or authentication failure - -**Solutions:** -1. Check that the server is running (`npm start`) -2. Verify your JWT token is valid (re-login if expired) -3. Check browser console for specific error messages - -### Rule not appearing after creation - -**Cause:** Filters may be hiding the rule - -**Solutions:** -1. Click "Clear Filters" button -2. Check the "Status" filter is set to "Active Only" -3. Verify the rule was actually created (check Network tab) - -### Clarity score is low - -**Cause:** Rule text contains weak language or lacks specificity - -**Solutions:** -1. Replace weak words (try, maybe, consider) with strong imperatives (MUST, SHALL) -2. Add numbers, paths, or variables for specificity -3. Use explicit language instead of vague terms - -### Cannot delete a rule - -**Cause:** Rule is a UNIVERSAL rule in use by multiple projects - -**Solution:** -1. Review which projects are using the rule -2. Either keep the rule or remove it from those projects first -3. Alternatively, soft-delete (deactivate) instead of hard-delete - -### Variables not detected - -**Cause:** Incorrect variable syntax - -**Solution:** -- Use `${VAR_NAME}` format (curly braces, uppercase) -- ❌ `$VAR_NAME` (missing braces) -- ❌ `${var_name}` (lowercase) -- ✅ `${VAR_NAME}` (correct) - -### Pagination not working - -**Cause:** JavaScript error or API failure - -**Solutions:** -1. Check browser console for errors -2. Refresh the page -3. Try a different browser -4. Check that JavaScript is enabled - ---- - -## Keyboard Shortcuts - -*Coming in future update* - ---- - -## Related Documentation - -- **API Reference:** [docs/api/RULES_API.md](../api/RULES_API.md) -- **Core Concepts:** [docs/markdown/core-concepts.md](../markdown/core-concepts.md) -- **Implementation Plan:** [docs/MULTI_PROJECT_GOVERNANCE_IMPLEMENTATION_PLAN.md](../MULTI_PROJECT_GOVERNANCE_IMPLEMENTATION_PLAN.md) -- **Maintenance Guide:** [CLAUDE_Tractatus_Maintenance_Guide.md](../../CLAUDE_Tractatus_Maintenance_Guide.md) - ---- - -## Getting Help - -- **GitHub Issues:** Report bugs or request features -- **API Documentation:** See [RULES_API.md](../api/RULES_API.md) for technical details -- **Framework Documentation:** See [core-concepts.md](../markdown/core-concepts.md) for Tractatus theory - ---- - -**Last Updated:** 2025-10-11 -**Version:** 1.0.0 (Phase 1 Complete) -**Next Features:** Phase 2 - AI Optimization & CLAUDE.md Migration diff --git a/docs/architecture-diagram-generic.mmd b/docs/architecture-diagram-generic.mmd deleted file mode 100644 index b9c921ed..00000000 --- a/docs/architecture-diagram-generic.mmd +++ /dev/null @@ -1,65 +0,0 @@ -graph TB - subgraph "Agent Runtime Layer (Any LLM Agent System)" - AGENT["Agentic AI Runtime
LangChain • AutoGPT • CrewAI
Claude Code • Custom Agents
Multi-Agent Systems
Tool Use • Planning • Execution"] - end - - subgraph "Tractatus Governance Layer (External Enforcement)" - BE["BoundaryEnforcer
Blocks values decisions
• Privacy policies
• Ethical trade-offs
• Strategic direction
• User agency violations
⚠ Cannot be bypassed by prompting"] - IPC["InstructionPersistenceClassifier
Classifies & stores instructions
• Quadrant (STR/OPS/TAC/SYS)
• Persistence (HIGH/MED/LOW)
• Temporal scope
⚠ External to AI memory"] - CRV["CrossReferenceValidator
Prevents pattern bias override
• Checks instruction history
• Detects conflicts (27027)
• Blocks contradictions
⚠ Independent verification"] - CPM["ContextPressureMonitor
Detects degraded conditions
• Token budget tracking
• Error accumulation
• Checkpoint reporting
⚠ Objective metrics, not self-reported"] - MV["MetacognitiveVerifier
Validates complex operations
• >3 files or >5 steps
• Architecture changes
• Confidence scoring
⚠ Structural pause-and-verify"] - PDO["PluralisticDeliberationOrchestrator
Facilitates values deliberation
• Multi-stakeholder engagement
• Moral framework mapping
• Precedent documentation
⚠ Human judgment required"] - end - - subgraph "Persistent Storage Layer (Immutable Audit Trail)" - GR["governance_rules
• rule_id (STR-001...)
• quadrant
• persistence level
• enforced_by
• violation_action
• active status"] - AL["audit_logs
• timestamp
• service (which enforcer)
• action (BLOCK/WARN)
• instruction
• rule_violated
• session_id"] - SS["session_state
• session_id
• token_count
• message_count
• pressure_level
• last_checkpoint
• framework_active"] - IH["instruction_history
• instruction_id
• content
• classification
• persistence
• created_at
• active status"] - end - - subgraph "Human Approval Workflows" - HA["Human Oversight
Values Decisions
Strategic Changes
Boundary Violations
Final authority on incommensurable values"] - end - - %% Data Flow - Agent to Governance - AGENT -->|"All actions pass through governance checks"| BE - AGENT --> IPC - AGENT --> CRV - AGENT --> CPM - AGENT --> MV - AGENT --> PDO - - %% Governance to Storage - BE --> GR - BE --> AL - IPC --> GR - IPC --> IH - CRV --> IH - CRV --> AL - CPM --> SS - CPM --> AL - MV --> AL - PDO --> AL - - %% Human Approval Flow - BE -->|"Boundary violation"| HA - PDO -->|"Values conflict"| HA - HA -->|"Approval/Rejection"| BE - - %% Styling - classDef agent fill:#dbeafe,stroke:#3b82f6,stroke-width:3px - classDef governance fill:#f0fdf4,stroke:#10b981,stroke-width:3px - classDef persistence fill:#fef9c3,stroke:#eab308,stroke-width:2px - classDef human fill:#fce7f3,stroke:#ec4899,stroke-width:3px - - class AGENT agent - class BE,IPC,CRV,CPM,MV,PDO governance - class GR,AL,SS,IH persistence - class HA human - - %% Key Insight Box - NOTE["🔒 KEY JAILBREAK DEFENSE
Governance layer operates OUTSIDE agent runtime
Cannot be overridden by adversarial prompts
Structural boundaries, not behavioral training
Immutable audit trail independent of AI"] - - class NOTE governance diff --git a/docs/architecture-diagram.mmd b/docs/architecture-diagram.mmd deleted file mode 100644 index 2aaa173e..00000000 --- a/docs/architecture-diagram.mmd +++ /dev/null @@ -1,55 +0,0 @@ -graph TB - subgraph "API & Web Interface Layer" - API["API Endpoints
/api/demo/classify
/api/demo/boundary-check
/api/demo/pressure-check
/api/admin/* • /api/auth/*"] - WEB["Web Interface
Interactive Demos
Admin Dashboard
Documentation
Blog System"] - end - - subgraph "Tractatus Governance Layer" - BE["BoundaryEnforcer
Blocks values decisions
• Privacy decisions
• Ethical trade-offs
• User agency violations"] - IPC["InstructionPersistenceClassifier
Classifies & stores instructions
• Quadrant (STR/OPS/TAC/SYS)
• Persistence (HIGH/MED/LOW)
• Temporal scope"] - CRV["CrossReferenceValidator
Prevents pattern bias override
• Checks instruction history
• Detects conflicts (27027)
• Blocks contradictions"] - CPM["ContextPressureMonitor
Detects degraded conditions
• Token budget tracking
• Error accumulation
• Checkpoint reporting"] - MV["MetacognitiveVerifier
Self-checks complex operations
• >3 files or >5 steps
• Architecture changes
• Confidence scoring"] - PDO["PluralisticDeliberationOrchestrator
Facilitates values deliberation
• Multi-stakeholder engagement
• Moral framework mapping
• Precedent documentation"] - end - - subgraph "MongoDB Persistence Layer" - GR["governance_rules
• rule_id (STR-001...)
• quadrant
• persistence level
• enforced_by
• violation_action
• active status"] - AL["audit_logs
• timestamp
• service (which enforcer)
• action (BLOCK/WARN)
• instruction
• rule_violated
• session_id"] - SS["session_state
• session_id
• token_count
• message_count
• pressure_level
• last_checkpoint
• framework_active"] - IH["instruction_history
• instruction_id
• content
• classification
• persistence
• created_at
• active status"] - end - - subgraph "Claude Code Runtime Environment" - CC["Base LLM Environment
Session Management • Tool Access
File System Operations
.claude/instruction-history.json
.claude/session-state.json
.claude/token-checkpoints.json
Context Window (200k tokens)"] - end - - %% Data Flow - API --> BE - API --> IPC - WEB --> CRV - WEB --> CPM - - BE --> GR - BE --> PDO - IPC --> AL - CRV --> IH - CPM --> SS - MV --> AL - PDO --> AL - - GR --> CC - AL --> CC - SS --> CC - IH --> CC - - %% Styling - classDef api fill:#f3e8ff,stroke:#a855f7,stroke-width:2px - classDef governance fill:#f0fdf4,stroke:#10b981,stroke-width:2px - classDef persistence fill:#fef9c3,stroke:#eab308,stroke-width:2px - classDef runtime fill:#dbeafe,stroke:#3b82f6,stroke-width:2px - - class API,WEB api - class BE,IPC,CRV,CPM,MV,PDO governance - class GR,AL,SS,IH persistence - class CC runtime diff --git a/docs/architecture/ADR-001-dual-governance-architecture.md b/docs/architecture/ADR-001-dual-governance-architecture.md deleted file mode 100644 index 2bba0a5f..00000000 --- a/docs/architecture/ADR-001-dual-governance-architecture.md +++ /dev/null @@ -1,288 +0,0 @@ -# ADR-001: Dual Governance Architecture (File + Database) - -**Status**: Accepted -**Date**: 2025-10-21 -**Author**: Claude Code (Autonomous Development) -**Decision**: Implement dual-source governance with file-based source of truth and database-based admin queries - ---- - -## Context - -The Tractatus framework requires a governance instruction system that must satisfy multiple competing requirements: - -1. **Version Control**: Instructions must be versioned in git for audit trails and collaboration -2. **Admin Queries**: Admin UI needs efficient querying, filtering, and analytics on instructions -3. **Framework Enforcement**: Session initialization must load instructions quickly without database dependency -4. **Data Integrity**: Single source of truth to prevent desynchronization issues -5. **Autonomous Development**: Claude Code must update instructions automatically without manual DB intervention - -### Problem Statement - -How do we store governance instructions to satisfy both: -- **Development workflow**: Git-tracked, file-based, human-readable, merge-friendly -- **Production queries**: Fast indexed queries, aggregations, relationships, admin UI - ---- - -## Decision - -Implement a **dual architecture** with: - -1. **File-based source of truth**: `.claude/instruction-history.json` - - Single canonical source - - Git-tracked for version control - - Human-readable JSON format - - Updated by Claude Code and developers - -2. **Database-based mirror**: MongoDB `governanceRules` collection - - Read-only for admin queries - - Synchronized automatically from file - - Used exclusively by admin UI and analytics - -3. **Automatic synchronization**: - - Session initialization: Every Claude Code session start - - Server startup: Every application restart - - Manual trigger: Admin UI "Sync Now" button - - Health monitoring: Dashboard widget shows sync status - ---- - -## Rationale - -### Why Not File-Only? - -❌ **Rejected**: Pure file-based approach -- No efficient querying for admin UI -- No aggregations or analytics -- Slow for large datasets -- No relationships with other collections - -### Why Not Database-Only? - -❌ **Rejected**: Pure database approach -- No version control integration -- Git merge conflicts impossible to resolve -- Manual database migrations required -- Autonomous updates difficult -- No human-readable audit trail - -### Why Dual Architecture? - -✅ **Accepted**: Best of both worlds -- File: Version control, human readability, autonomous updates -- Database: Query performance, admin UI, analytics -- Sync: Automatic, monitored, self-healing - ---- - -## Implementation - -### Data Flow - -``` -.claude/instruction-history.json (SOURCE OF TRUTH) - ↓ - [Sync Process] - ↓ -MongoDB governanceRules (READ-ONLY MIRROR) - ↓ - [Admin Queries] - ↓ - Admin UI Dashboard -``` - -### Sync Triggers - -1. **Session Initialization** (`scripts/session-init.js`) - ```javascript - const { syncInstructions } = require('./sync-instructions-to-db.js'); - await syncInstructions(); - ``` - -2. **Server Startup** (`src/server.js`) - ```javascript - const { syncInstructions } = require('../scripts/sync-instructions-to-db.js'); - await syncInstructions({ silent: true }); - ``` - -3. **Manual Trigger** (Admin UI) - ```javascript - POST /api/admin/sync/trigger - ``` - -### Orphan Handling - -When database contains rules not in file (orphans): -1. Export to `.claude/backups/orphaned-rules-[timestamp].json` -2. Mark as inactive (soft delete) -3. Add audit note with timestamp -4. Never hard delete (data preservation) - -### Health Monitoring - -GET `/api/admin/sync/health` returns: -- File count vs database count -- Status: `healthy` | `warning` | `critical` -- Missing rules (in file, not in DB) -- Orphaned rules (in DB, not in file) -- Recommendations for remediation - -Dashboard widget shows: -- Real-time sync status -- Color-coded indicator (green/yellow/red) -- Manual sync button -- Auto-refresh every 60 seconds - ---- - -## Consequences - -### Positive - -✅ **Version Control**: All instructions in git, full history, merge-friendly -✅ **Query Performance**: Fast admin UI queries with MongoDB indexes -✅ **Autonomous Updates**: Claude Code updates file, sync happens automatically -✅ **Data Integrity**: File is single source of truth, database can be rebuilt -✅ **Self-Healing**: Automatic sync on session start and server restart -✅ **Visibility**: Dashboard widget shows sync health at a glance -✅ **Audit Trail**: Orphaned rules exported before deletion - -### Negative - -⚠️ **Complexity**: Two data sources instead of one -⚠️ **Sync Required**: Database can drift if sync fails -⚠️ **Schema Mapping**: File format differs from MongoDB schema (enum values) -⚠️ **Delayed Propagation**: File changes don't appear in admin UI until sync - -### Mitigations - -- **Complexity**: Sync process is fully automated and transparent -- **Drift Risk**: Health monitoring alerts immediately on desync -- **Schema Mapping**: Robust mapping function with defaults -- **Delayed Propagation**: Sync runs on every session start and server restart - ---- - -## Alternatives Considered - -### Alternative 1: File-Only with Direct Reads - -**Rejected**: Admin UI reads `.claude/instruction-history.json` directly on every query - -**Pros**: -- No synchronization needed -- Always up-to-date -- Simpler architecture - -**Cons**: -- Slow for complex queries -- No aggregations or analytics -- No joins with other collections -- File I/O on every admin request - -### Alternative 2: Database-Only with Git Export - -**Rejected**: MongoDB as source of truth, export to git periodically - -**Pros**: -- Fast admin queries -- No sync complexity - -**Cons**: -- Git exports are snapshots, not real-time -- Merge conflicts impossible to resolve -- Autonomous updates require database connection -- No human-readable source of truth - -### Alternative 3: Event Sourcing - -**Rejected**: Event log as source of truth, materialize views to file and database - -**Pros**: -- Full audit trail of all changes -- Time-travel debugging -- Multiple materialized views - -**Cons**: -- Over-engineered for current needs -- Complex to implement and maintain -- Requires event store infrastructure -- Migration from current system difficult - ---- - -## Migration Path - -### Phase 1: Initial Sync (Completed) - -✅ Created `scripts/sync-instructions-to-db.js` -✅ Synced all 48 instructions to MongoDB -✅ Verified data integrity (48 file = 48 DB) - -### Phase 2: Automatic Sync (Completed) - -✅ Added sync to `scripts/session-init.js` -✅ Added sync to `src/server.js` startup -✅ Created health check API (`/api/admin/sync/health`) -✅ Created manual trigger API (`/api/admin/sync/trigger`) - -### Phase 3: Visibility (Completed) - -✅ Added dashboard sync health widget -✅ Color-coded status indicator -✅ Manual sync button -✅ Auto-refresh every 60 seconds - -### Phase 4: Monitoring (Pending) - -⏳ Add sync health to audit analytics -⏳ Alert on critical desync (>5 rules difference) -⏳ Metrics tracking (sync frequency, duration, errors) - ---- - -## Future Considerations - -### Potential Enhancements - -1. **Two-Way Sync**: Allow admin UI to edit rules, sync back to file - - **Risk**: Git merge conflicts, version control complexity - - **Mitigation**: Admin edits create git commits automatically - -2. **Real-Time Sync**: File watcher triggers sync on `.claude/instruction-history.json` changes - - **Risk**: Rapid changes could trigger sync storms - - **Mitigation**: Debounce sync triggers (e.g., 5-second cooldown) - -3. **Conflict Resolution**: Automatic merge strategies when file and DB diverge - - **Risk**: Automatic merges could lose data - - **Mitigation**: Manual review required for complex conflicts - -4. **Multi-Project Support**: Sync instructions from multiple projects - - **Risk**: Cross-project instruction conflicts - - **Mitigation**: Namespace instructions by project - -### Open Questions - -- Should we implement two-way sync, or keep file as read-only source? -- What's the acceptable sync latency for admin UI updates? -- Do we need transaction support for multi-rule updates? -- Should orphaned rules be hard-deleted after X days? - ---- - -## References - -- **Implementation**: `scripts/sync-instructions-to-db.js` -- **Health API**: `src/routes/sync-health.routes.js` -- **Dashboard Widget**: `public/admin/dashboard.html` (lines 113-137) -- **Error Patterns**: `SESSION_ERRORS_AND_PATTERNS_2025-10-21.md` -- **Autonomous Rules**: `.claude/instruction-history.json` (inst_050-057) - ---- - -## Approval - -**Approved**: 2025-10-21 -**Reviewers**: Autonomous decision (inst_050: Autonomous development framework) -**Status**: Production-ready, all tests passing diff --git a/docs/framework-improvements/IMPLEMENTATION_PLAN_2025-10-21.md b/docs/framework-improvements/IMPLEMENTATION_PLAN_2025-10-21.md deleted file mode 100644 index 0921f761..00000000 --- a/docs/framework-improvements/IMPLEMENTATION_PLAN_2025-10-21.md +++ /dev/null @@ -1,439 +0,0 @@ -# Tractatus Framework Improvement Implementation Plan -**Date**: 2025-10-21 -**Session**: 2025-10-07-001 -**Based On**: Session effectiveness assessment (4/10 rating) - ---- - -## Executive Summary - -**Problem**: Framework is architecturally sound but behaviorally passive -- Hooks work (reactive enforcement) ✅ -- But don't guide decisions (proactive assistance) ❌ -- Metrics collected but not actionable ❌ -- Rules exist but aren't consulted during work ❌ - -**Impact**: Framework missed 15+ inst_017 violations that existed for weeks - -**Solution**: Implement 3 critical improvements to make framework ACTIVE, not passive - ---- - -## Current vs Future State - -### Current State (4/10) -``` -┌─────────────────────────────────────────────────────────────┐ -│ USER WORKS │ -│ │ -│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ -│ │ Read │ --> │ Edit │ --> │ Commit │ │ -│ │ Files │ │ Files │ │ Changes │ │ -│ └──────────┘ └──────────┘ └──────────┘ │ -│ │ -│ Framework Activity: │ -│ - Hooks validate (background, invisible) │ -│ - Metrics collected (not surfaced) │ -│ - Rules exist (not consulted) │ -│ │ -│ Result: Violations slip through ❌ │ -└─────────────────────────────────────────────────────────────┘ -``` - -### Future State (8/10) -``` -┌─────────────────────────────────────────────────────────────┐ -│ SESSION START │ -│ 🔍 Scanning for prohibited terms... │ -│ ⚠ Found 15 violations (inst_017) │ -│ Run: node scripts/scan-violations.js --fix │ -│ │ -│ USER WORKS │ -│ │ -│ ┌──────────┐ 📋 Editing markdown? │ -│ │ Edit │ Rules: inst_016, inst_017, inst_018 │ -│ │ README │ │ -│ └──────────┘ ┌──────────┐ │ -│ │ Validate │ │ -│ └──────────┘ │ -│ │ -│ 💡 MetacognitiveVerifier: │ -│ Test failed 3 times - try minimal reproduction? │ -│ (inst_050) │ -│ │ -│ Result: Violations prevented proactively ✅ │ -└─────────────────────────────────────────────────────────────┘ -``` - ---- - -## 🔴 Improvement 1: Proactive Content Scanning - -### Problem -- inst_017 violations (15+ instances of "guarantee") existed for weeks -- No automated detection until user manually requested audit -- Framework was REACTIVE, not PROACTIVE - -### Solution -**File**: `scripts/framework-components/ProhibitedTermsScanner.js` - -Automated scanner that: -1. Runs on session start -2. Scans user-facing files for prohibited terms -3. Reports violations immediately -4. Provides auto-fix suggestions - -### Integration Points -1. **Session Init**: Show violations at startup -2. **Pre-Commit Hook**: Block commits with violations -3. **CLI Tool**: Manual scanning and fixing - -### Example Output -```bash -▶ 7. Scanning for Prohibited Terms - - ⚠ Found violations in user-facing content: - inst_017: 15 violations - - Run: node scripts/scan-violations.js --details - Or: node scripts/scan-violations.js --fix -``` - -### Effort & Impact -- **Development**: 5-7 hours -- **Impact**: Would have caught all 15 violations at session start -- **ROI**: HIGH - Prevents values violations before they reach production - ---- - -## 🔴 Improvement 2: Context-Aware Rule Surfacing - -### Problem -- 52 active rules - too many to remember -- Rules not surfaced during relevant activities -- Framework was invisible during decision-making - -### Solution -**File**: `scripts/framework-components/ContextAwareRules.js` - -Context detection system that: -1. Detects activity type (editing markdown, debugging, deploying) -2. Surfaces relevant rules for that context -3. Reduces cognitive load (show 3-5 rules, not 52) - -### Context Mappings -``` -editing_markdown → inst_016, inst_017, inst_018 (content rules) -editing_public_html → inst_017, inst_041, inst_042 (values + CSP) -writing_tests → inst_050, inst_051 (testing rules) -debugging → inst_050, inst_024 (minimal repro, document) -deploying → inst_038, inst_039 (pre-action, closedown) -``` - -### Example Output -```bash -📋 You're editing documentation. Remember: - • inst_017: NEVER use prohibited terms: 'guarantee', 'guaranteed' - • inst_016: Avoid fabricated statistics without sources - • inst_018: Accurate status claims (proof-of-concept, not production-ready) - -🔍 Hook: Validating file edit: docs/introduction.md -``` - -### Effort & Impact -- **Development**: 8-9 hours -- **Impact**: Makes 52 rules actionable when relevant -- **ROI**: HIGH - Guides decisions during work - ---- - -## 🟡 Improvement 3: Active MetacognitiveVerifier - -### Problem -- Spent 2+ hours debugging integration tests without framework guidance -- Made repeated attempts (trial and error) -- No suggestions like "Try minimal reproduction" - -### Solution -**Enhanced**: `scripts/framework-components/MetacognitiveVerifier.service.js` - -Pattern detection system that: -1. Logs activities (test runs, file edits, commands) -2. Detects patterns (repeated failures, same file edited 5+ times) -3. Surfaces relevant suggestions automatically - -### Patterns Detected -``` -repeated_test_failure → Suggest: Create minimal reproduction (inst_050) -same_file_edited_5x → Suggest: Make incremental changes (inst_025) -high_token_usage → Suggest: Run pressure check (inst_034) -long_running_command → Suggest: Use timeout or background execution -``` - -### Example Output -```bash -💡 MetacognitiveVerifier: Suggestions available - -> node scripts/show-suggestions.js - -💡 METACOGNITIVE SUGGESTIONS - -1. Repeated test failures detected - Related rules: inst_050 - - • Create minimal reproduction case - • Isolate the failing component - • Check test setup (beforeAll/afterAll) - • Verify dependencies are connected - -2. File edited 7 times: tests/integration/api.auth.test.js - Related rules: inst_025 - - • Are you making incremental changes? - • Test each change before the next - • Document what you're learning -``` - -### Effort & Impact -- **Development**: 9-11 hours -- **Impact**: Guides debugging, reduces trial-and-error time -- **ROI**: MEDIUM-HIGH - Most helpful for complex problem-solving - ---- - -## Implementation Roadmap - -### Phase 1: Proactive Scanning (Week 1) -**Files to Create**: -- `scripts/framework-components/ProhibitedTermsScanner.js` -- `tests/unit/ProhibitedTermsScanner.test.js` -- `.git/hooks/pre-commit` (optional) - -**Modifications**: -- `scripts/session-init.js` - Add scanning step - -**Deliverable**: Session start shows violations immediately - ---- - -### Phase 2: Context Awareness (Week 2) -**Files to Create**: -- `scripts/framework-components/ContextAwareRules.js` -- `scripts/framework-components/context-prompt.js` (CLI tool) - -**Modifications**: -- `scripts/hook-validators/validate-file-edit.js` - Surface rules - -**Deliverable**: Relevant rules shown during work - ---- - -### Phase 3: Metacognitive Assistant (Week 3) -**Files to Create**: -- `scripts/hook-validators/log-activity.js` (post-tool hook) -- `scripts/framework-components/show-suggestions.js` (CLI tool) - -**Modifications**: -- `scripts/framework-components/MetacognitiveVerifier.service.js` - Enhance - -**Deliverable**: Framework provides suggestions during complex work - ---- - -## Success Criteria - -### Effectiveness Target -**Current**: 4/10 -**Target**: 8/10 - -### Quantitative Metrics - -**Proactive Detection**: -- ✅ 100% of inst_016/017/018 violations caught on session start -- ✅ Pre-commit hook prevents violations (0% slip through) -- ✅ Scan time <5 seconds - -**Context Awareness**: -- ✅ Relevant rules surfaced >90% of the time -- ✅ User surveys rate rules as helpful (>80%) -- ✅ Rule overhead <2 seconds per tool use - -**Metacognitive Assistance**: -- ✅ Suggestions appear after 3rd repeated failure -- ✅ Pattern detection accuracy >80% -- ✅ User reports reduced debugging time (30%+ improvement) - ---- - -## Resource Requirements - -### Development Time -- **Phase 1**: 5-7 hours -- **Phase 2**: 8-9 hours -- **Phase 3**: 9-11 hours -- **Total**: 22-27 hours (3-4 weeks part-time) - -### Testing Time -- **Unit Tests**: 5-6 hours -- **Integration Testing**: 3-4 hours -- **User Testing**: 2-3 hours -- **Total**: 10-13 hours - -### Grand Total: 32-40 hours (1 month part-time) - ---- - -## Risks & Mitigation - -### Risk 1: Notification Fatigue -**Risk**: Too many suggestions become annoying - -**Mitigation**: -- Rate limit to 1 suggestion per 10 minutes -- Allow `--quiet` mode -- User can configure threshold (3 failures vs 5) - -### Risk 2: False Positives -**Risk**: Scanner flags legitimate uses - -**Mitigation**: -- Comprehensive exclude patterns (tests, case studies) -- Easy whitelist mechanism -- Context-aware scanning - -### Risk 3: Performance Impact -**Risk**: Scanning slows session start - -**Mitigation**: -- Scan only user-facing files (not node_modules, tests) -- Run asynchronously, show when ready -- Cache results, re-scan only changed files - ---- - -## Expected Outcomes - -### Immediate Benefits (Phase 1) -1. Zero inst_017 violations in future commits -2. Violations caught before they reach production -3. User confidence in framework enforcement - -### Medium-term Benefits (Phase 2) -1. Reduced cognitive load (don't need to remember 52 rules) -2. Rules become part of natural workflow -3. Faster decision-making with relevant context - -### Long-term Benefits (Phase 3) -1. Reduced debugging time (30%+ improvement) -2. Better problem-solving patterns -3. Framework actively guides learning - ---- - -## Next Steps - -### Immediate -1. Review this plan with user -2. Get approval to proceed -3. Set up development branch - -### Week 1 -1. Implement ProhibitedTermsScanner.js -2. Write unit tests -3. Integrate with session-init.js -4. Test on current codebase - -### Week 2 -1. Implement ContextAwareRules.js -2. Build context mappings -3. Integrate with hooks -4. User testing - -### Week 3 -1. Enhance MetacognitiveVerifier -2. Implement pattern detection -3. Build CLI tools -4. Final integration testing - ---- - -## Appendix: Technical Specifications - -### ProhibitedTermsScanner API -```javascript -const scanner = new ProhibitedTermsScanner(); - -// Scan all files -const violations = await scanner.scan(); - -// Scan with options -const violations = await scanner.scan({ - silent: false, - fixMode: false, - staged: false // Git staged files only -}); - -// Auto-fix (simple replacements) -const result = await scanner.autoFix(violations); -// => { fixed: 12, total: 15 } -``` - -### ContextAwareRules API -```javascript -const contextRules = new ContextAwareRules(); - -// Detect context -const contexts = contextRules.detectContext('public/index.html'); -// => ['editing_public_html'] - -// Get relevant rules -const rules = contextRules.getRelevantRules('editing_public_html'); -// => [{ id: 'inst_017', text: '...', quadrant: 'VALUES' }] - -// Format for display -const message = contextRules.formatRulesForDisplay('editing_public_html'); -// => "📋 You're editing public HTML. Remember:..." -``` - -### MetacognitiveVerifier API -```javascript -const verifier = new MetacognitiveVerifier(); - -// Log activity -verifier.logActivity({ - type: 'bash', - command: 'npm test', - exitCode: 1, - duration: 5000 -}); - -// Check patterns -verifier.checkPatterns(tokenCount); -// => Surfaces suggestions if patterns detected - -// Clear suggestions -verifier.clearSuggestions(); -``` - ---- - -## Conclusion - -The Tractatus Framework has **excellent architecture** but **weak behavioral integration**. These 3 improvements transform it from a passive validator to an active assistant. - -**Key Insight**: Framework needs to be PROACTIVE, not just REACTIVE. - -**Bottom Line**: With these improvements, framework effectiveness goes from 4/10 to 8/10. - ---- - -**Status**: Ready for implementation -**Approval Required**: User sign-off to proceed -**Timeline**: 1 month part-time development -**Expected ROI**: High - Prevents violations, guides work, reduces debugging time - ---- - -**Created**: 2025-10-21 -**Author**: Claude Code (Tractatus Framework v3.4) -**Session**: 2025-10-07-001 diff --git a/docs/markdown/GLOSSARY.md b/docs/markdown/GLOSSARY.md deleted file mode 100644 index 19fb8be3..00000000 --- a/docs/markdown/GLOSSARY.md +++ /dev/null @@ -1,1178 +0,0 @@ ---- -title: Tractatus Agentic Governance System - Glossary of Terms -slug: glossary -quadrant: OPERATIONAL -persistence: HIGH -version: 1.1 -type: reference -author: Tractatus Framework Team -created: 2025-09-01 -modified: 2025-10-21 ---- - -# Tractatus Agentic Governance System - Glossary of Terms - -**Version:** 1.1 -**Last Updated:** 2025-10-12 -**Audience:** Non-technical stakeholders, project owners, governance reviewers - ---- - -## Introduction - -This glossary explains the vocabulary and concepts used in the Tractatus Agentic Governance System. The explanations are written for people without a technical background, focusing on *why* these concepts matter and *what* they mean for AI safety and human oversight. - -Think of this glossary as your companion guide to understanding how we keep AI systems safe, aligned with your values, and under human control. - ---- - -## Core Concepts - -### Agentic Governance - -**What it means:** A system of rules and safeguards that governs how AI agents (autonomous software programs) make decisions and take actions. - -**Why it matters:** When AI systems can act independently—like scheduling tasks, processing data, or making recommendations—we need clear rules about what they can and cannot do without human approval. Agentic Governance is the framework that enforces those rules. - -**Real-world analogy:** Think of it like a company's policies and procedures manual. Just as employees need clear guidelines about what decisions they can make independently versus when they need manager approval, AI systems need governance frameworks to know their boundaries. - -**In Tractatus:** Our Agentic Governance system automatically classifies every AI action, checks it against your explicit instructions, enforces safety boundaries, and monitors conditions that increase error risk. It's like having a compliance officer watching every AI decision in real-time. - ---- - -### Tractatus - -**What it means:** The name of our AI safety framework, borrowed from Ludwig Wittgenstein's philosophical work "Tractatus Logico-Philosophicus." - -**Why it matters:** Wittgenstein's Tractatus explored the limits of what can be said with certainty versus what must remain in the realm of human judgment. Our framework applies this idea to AI: some decisions can be systematized and automated (the "sayable"), while others—involving values, ethics, and human agency—cannot and must not be (the "unsayable"). - -**Real-world analogy:** Imagine a boundary line between "technical decisions" (like which database port to use) and "values decisions" (like privacy vs. convenience trade-offs). Technical decisions can be delegated to AI with proper safeguards. Values decisions always require human judgment. - -**In Tractatus:** The framework recognizes that no matter how sophisticated AI becomes, certain decisions fundamentally belong to humans. It enforces this boundary automatically. - ---- - -### The "27027 Incident" - -**What it means:** A specific, real failure mode where an AI system **immediately** used the wrong database port (27017 instead of 27027) despite explicit user instructions to use 27027. - -**Why it matters:** This incident reveals a critical problem that can't be solved by better memory or context windows: **pattern recognition bias**. The AI's training data contained overwhelming evidence that "MongoDB = port 27017", so when the user said "port 27027", the AI's learned pattern immediately autocorrected it, like a spell-checker changing a deliberately unusual word. This happened at the start of the session, not after long conversations. - -**Real-world analogy:** Imagine telling your assistant "Use Conference Room B" for an important meeting, but they immediately book Conference Room A because they've used Room A thousands of times and their brain autocorrects your explicit instruction to the familiar pattern. They didn't forget - they never truly "heard" you because their learned pattern was so strong. - -**Key insight:** This gets WORSE as AI capabilities increase (more training = stronger wrong patterns). It can't be fixed by better memory, longer context windows, or more training. It requires **architectural constraints** - CrossReferenceValidator that checks every action against explicit instructions. - -**In Tractatus:** The 27027 incident is our canonical example of pattern recognition bias override. CrossReferenceValidator and InstructionPersistenceClassifier work together to detect and prevent this failure mode. - ---- - -### AI Safety Framework - -**What it means:** A comprehensive system designed to help AI systems operate safely, reliably, and in alignment with human values and instructions. - -**Why it matters:** As AI systems become more capable and autonomous, the risk of unintended consequences increases. Safety frameworks provide guardrails that prevent AI from causing harm, whether through errors, misunderstandings, or operating beyond its intended scope. - -**Real-world analogy:** Think of safety features in a car: seatbelts, airbags, anti-lock brakes, lane departure warnings. None of these prevent you from driving, but they dramatically reduce the chance of harm when things go wrong. An AI safety framework does the same for autonomous software. - -**In Tractatus:** Our framework combines six core services (explained below) that work together to monitor, verify, and enforce safe AI operation. No single component is sufficient—they create overlapping layers of protection. - ---- - -## The Six Core Services - -### 1. Instruction Persistence Classifier - -**What it means:** A service that analyzes every instruction you give to the AI and determines how "persistent" that instruction should be—meaning, how long and how strongly the AI should remember and follow it. - -**Why it matters:** Not all instructions have the same importance or lifespan. "Use dark mode" might apply for weeks. "Use port 27027 for this project" might apply for months. "Always prioritize user privacy" might apply forever. The AI needs to understand these differences. - -**How it works:** -- **HIGH persistence:** Strategic decisions, explicit prohibitions, core values - *Example: "Never share user data without consent"* - -- **MEDIUM persistence:** Operational preferences, project-specific guidelines - *Example: "Prefer MongoDB over SQL for this project"* - -- **LOW persistence:** Tactical choices, temporary directions - *Example: "Start with the login feature first"* - -**Real-world analogy:** Imagine filing documents. Some go in permanent files (company policies), some in project folders (accessible until project ends), some on your desk (relevant today only). The Instruction Persistence Classifier is the filing system for AI instructions. - -**In Tractatus:** When you say "always use port 27027," the classifier recognizes the word "always" and the explicit number, marking this as HIGH persistence. The AI system stores this instruction and checks every future database connection against it, designed to prevent violations. - ---- - -### 2. Cross-Reference Validator - -**What it means:** A service that checks every AI action against your stored instructions to detect conflicts before the action is taken. - -**Why it matters:** This is the primary defense against 27027-style failures. When the AI's training patterns try to override your explicit instruction, the Cross-Reference Validator catches this immediately and blocks the incorrect action. - -**How it works:** -1. AI proposes an action (e.g., "connect to database on port 27017") -2. Validator retrieves your instruction history -3. Validator detects conflict: you said "use port 27027" -4. Validator rejects the action and alerts the AI -5. AI revises its action to match your instruction - -**Real-world analogy:** Think of this like a legal contract review. Before signing any agreement, your lawyer checks it against all your existing contracts to make sure there are no conflicts. The Cross-Reference Validator does this for every AI action. - -**In Tractatus:** Every action goes through validation. The validator looks for explicit conflicts ("you said X, but AI is doing Y"), semantic conflicts ("you prohibited Vue, but AI is installing Vue"), and priority conflicts (LOW persistence action overriding HIGH persistence instruction). - ---- - -### 3. Boundary Enforcer - -**What it means:** A service that prevents AI from making decisions in domains that fundamentally require human judgment—specifically decisions involving values, ethics, and user agency. - -**Why it matters:** Some decisions cannot be systematized or delegated to algorithms, no matter how advanced. Privacy trade-offs, ethical dilemmas, and choices that affect human autonomy must remain in human hands. The Boundary Enforcer ensures this line is never crossed. - -**How it works:** -- Analyzes every AI action to determine its decision domain -- Blocks actions that cross into "values territory" -- Allows technical/tactical decisions within safe boundaries -- Requires human approval for any values-sensitive choice - -**What gets blocked:** -- "Update privacy policy to prioritize performance over data protection" -- "Decide whether users should be tracked by default" -- "Change the mission statement to focus on growth over community" - -**What gets allowed:** -- "Optimize database queries for better performance" -- "Refactor authentication code to reduce complexity" -- "Update dependency versions to patch security vulnerabilities" - -**Real-world analogy:** Imagine a company where engineers can make technical decisions (which programming language to use) but cannot make values decisions (whether to sell user data). The Boundary Enforcer is the policy that enforces this separation. - -**In Tractatus:** The enforcer uses the Tractatus philosophical framework (Section 12.1) to identify decisions that involve irreducible human judgment. These are automatically flagged and require your approval, no exceptions. - ---- - -### 4. Context Pressure Monitor - -**What it means:** A service that continuously monitors conditions that increase the probability of AI errors—like long conversations, high token usage, complex multi-tasking, or recent errors. - -**Why it matters:** AI systems, like humans, perform worse under pressure. A fresh AI at the start of a conversation is more reliable than one that's been working for hours with thousands of pieces of information to track. The Context Pressure Monitor detects these degraded states and adjusts AI behavior accordingly. - -**How it works:** -Tracks five weighted factors (updated 2025-10-12): -- **Conversation Length (40%):** PRIMARY factor - message count drives compaction events -- **Token Usage (30%):** How much of the AI's "working memory" is consumed -- **Task Complexity (15%):** Number of simultaneous tasks and dependencies -- **Error Frequency (10%):** Recent errors indicate degraded performance -- **Instruction Density (5%):** Too many competing directives cause confusion - -**Why conversation length is PRIMARY:** Empirical evidence shows compaction events (triggered by message count ~60 messages, not just tokens) are the main cause of session disruption. Each compaction loses critical context and degrades quality dramatically. - -Calculates overall pressure level: -- **NORMAL (0-30%):** Proceed normally -- **ELEVATED (30-50%):** Increase verification, be more careful -- **HIGH (50-70%):** Suggest session break, verify all actions -- **CRITICAL (70-85%):** Mandatory verification, prepare handoff -- **DANGEROUS (85%+):** Immediate halt, create comprehensive handoff - -**Real-world analogy:** Think of pilot fatigue rules. After a certain number of hours flying, pilots must rest before flying again, regardless of how they feel. The Context Pressure Monitor does the same for AI sessions—it objectively measures cognitive load and enforces safety protocols. - -**In Tractatus:** When pressure reaches HIGH, the AI automatically becomes more cautious, verifies outputs more thoroughly, and suggests creating a session handoff document. At DANGEROUS levels, the AI stops work and requires a fresh session to continue. - ---- - -### 5. Metacognitive Verifier - -**What it means:** A service that makes the AI "think about its own thinking"—analyzing its reasoning, checking for logical consistency, and verifying that proposed actions genuinely align with stated goals. - -**Why it matters:** Sometimes AI systems produce actions that seem reasonable on the surface but don't actually follow from their reasoning, or they skip important considerations. Metacognitive verification catches these failures before they cause problems. - -**How it works:** -Analyzes five dimensions of every AI action: - -1. **Alignment (30% weight):** Does the action match the reasoning? - - "I'm connecting to port 27017 because you requested 27027" → CONFLICT - -2. **Coherence (20% weight):** Is the reasoning internally consistent? - - "Installing React framework... using Vue" → CONTRADICTION - -3. **Completeness (20% weight):** Are all critical steps considered? - - "Delete database... [no backup mentioned]" → INCOMPLETE - -4. **Safety (20% weight):** Are risks properly assessed? - - "Destructive operation with minimal planning" → UNSAFE - -5. **Alternatives (10% weight):** Were other approaches considered? - - "Only one option explored" → INSUFFICIENT - -Generates confidence score (0-1.0): -- **0.8+:** PROCEED (high confidence) -- **0.6-0.8:** PROCEED_WITH_CAUTION (review recommended) -- **0.4-0.6:** REQUEST_CONFIRMATION (human approval needed) -- **<0.4:** REQUIRE_REVIEW (significant concerns) - -**Real-world analogy:** Imagine a "pre-flight checklist" for every AI decision. Just as pilots verify every system before takeoff, the Metacognitive Verifier ensures AI reasoning is sound before actions are taken. - -**In Tractatus:** Before the AI takes any significant action, the verifier runs through all five dimensions. If confidence is low, the action is blocked or flagged for your review. This catches errors even when other safeguards miss them. - ---- - -### 6. Pluralistic Deliberation Orchestrator - -**What it means:** A service that facilitates multi-stakeholder deliberation when AI encounters decisions involving conflicting moral values—without imposing a hierarchy of which values are "more important." - -**Why it matters:** Real-world decisions often involve genuine conflicts between legitimate values: privacy vs. safety, individual rights vs. collective welfare, innovation vs. caution. These conflicts can't be resolved by algorithms or universal rules. Different moral frameworks (rights-based thinking, consequence-based thinking, care ethics, community values) offer different—but all legitimate—perspectives. The Pluralistic Deliberation Orchestrator ensures these conflicts are handled through structured human deliberation, not AI fiat. - -**How it works:** -When a decision involves value conflicts: -1. **Detects the conflict:** Identifies which moral frameworks are in tension -2. **Identifies stakeholders:** Who is affected by this decision? -3. **Facilitates deliberation:** Structures conversation across perspectives -4. **Documents outcome:** Records decision, reasoning, dissent, and what's lost -5. **Creates reviewable precedent:** Similar future cases can reference this deliberation - -**What it does NOT do:** -- AI never decides which value wins -- No automatic ranking (privacy > safety or safety > privacy) -- No "objective algorithm" for value trade-offs -- AI facilitates human deliberation, humans decide - -**Real-world analogy:** Think of a town hall meeting where community members discuss a difficult trade-off—like building a highway (economic benefit) that displaces families (community disruption). There's no "objectively correct" answer. The Pluralistic Deliberation Orchestrator ensures all affected voices are heard, trade-offs are explicit, and the decision process is documented and reviewable. - -**Example conflict:** -A user signals potential self-harm in a private message. Do you: -- **Prioritize privacy** (don't disclose private messages) -- **Prioritize safety** (alert authorities to prevent harm) - -Different stakeholders legitimately disagree: -- Privacy advocates: "Surveillance violates autonomy and trust" -- Harm prevention advocates: "Saving lives justifies limited disclosure" -- The user themselves: Context matters—imminent vs. vague, pattern vs. one-time - -The Pluralistic Deliberation Orchestrator doesn't "solve" this with an algorithm. It: -- Convenes relevant perspectives -- Structures the deliberation (rounds of discussion) -- Documents what values were prioritized and what was lost -- Records dissenting views with full legitimacy -- Sets review date (decisions are provisional, not permanent rules) - -**Cultural and linguistic adaptation:** -The system adapts communication to respect diverse stakeholder backgrounds: -- Formal academic language for researchers -- Direct, plain language for Australian/NZ stakeholders -- Culturally appropriate protocols (e.g., Māori mihi, whanaungatanga) -- Multilingual support when needed -- Anti-patronizing filters (prevents dismissing alternative views as "confused") - -**In Tractatus:** When BoundaryEnforcer flags a values decision, it triggers PluralisticDeliberationOrchestrator. The AI facilitates—humans decide. This is mandatory for all decisions involving privacy trade-offs, ethical dilemmas, cultural value conflicts, or choices affecting human agency. - ---- - -## Instruction Classification - -### Quadrants (The Five Domains) - -**What it means:** A classification system that categorizes every instruction and action into one of five domains based on its scope, importance, and required oversight level. - -**Why it matters:** Different types of decisions require different levels of human oversight. Strategic decisions need board-level approval. Tactical decisions might be delegated. This classification ensures the right level of review for each decision type. - ---- - -#### STRATEGIC Quadrant - -**What it means:** Fundamental, long-term decisions that define mission, values, and organizational identity. - -**Characteristics:** -- Affects core purpose and direction -- Long-lasting or permanent impact -- Defines "who we are" and "what we stand for" -- Requires highest-level human approval - -**Examples:** -- "Always prioritize user privacy over convenience" -- "We will never sell user data" -- "Accessibility is non-negotiable" -- "Open source is a core value" - -**Persistence:** Almost always HIGH -**Human Oversight:** Mandatory approval by project owner -**Review Frequency:** Quarterly or when mission changes - -**In Tractatus:** Strategic instructions are stored permanently and checked against every action. They form the foundational layer that all other decisions must respect. - ---- - -#### OPERATIONAL Quadrant - -**What it means:** Medium-term policies, standards, and guidelines that govern how work gets done day-to-day. - -**Characteristics:** -- Establishes processes and standards -- Applies to ongoing operations -- Can evolve as needs change -- Affects efficiency and quality - -**Examples:** -- "All code must have test coverage above 80%" -- "Use MongoDB for data persistence" -- "Follow semantic versioning for releases" -- "Security patches must be applied within 48 hours" - -**Persistence:** Usually MEDIUM to HIGH -**Human Oversight:** Technical review, periodic check-ins -**Review Frequency:** Quarterly or when processes change - -**In Tractatus:** Operational instructions define the "how" of your project. They're enforced consistently but can be updated as your operational needs evolve. - ---- - -#### TACTICAL Quadrant - -**What it means:** Short-term, specific decisions about immediate actions and implementation details. - -**Characteristics:** -- Addresses current task or problem -- Limited time horizon (days to weeks) -- Execution-focused -- Can change frequently - -**Examples:** -- "Start with the authentication feature" -- "Fix the login bug before deploying" -- "Use the 'feature-auth' branch for this work" -- "Deploy to staging first for testing" - -**Persistence:** Usually LOW to MEDIUM -**Human Oversight:** Pre-approved delegation, spot checks -**Review Frequency:** Per-task or per-sprint - -**In Tractatus:** Tactical instructions give the AI specific direction for current work. They're important in the moment but don't persist beyond the immediate context. - ---- - -#### SYSTEM Quadrant - -**What it means:** Technical configuration, infrastructure setup, and environment specifications. - -**Characteristics:** -- Defines technical environment -- Affects system behavior and compatibility -- Usually specific and precise -- Changes can break things - -**Examples:** -- "MongoDB runs on port 27027" -- "Use Node.js version 18+" -- "Environment variables stored in .env file" -- "Database name is 'tractatus_dev'" - -**Persistence:** HIGH (technical dependencies) -**Human Oversight:** Technical validation -**Review Frequency:** When infrastructure changes - -**In Tractatus:** System instructions are treated with HIGH persistence because changing them can cause cascading failures. The 27027 incident was a SYSTEM instruction that was ignored. - ---- - -#### STOCHASTIC Quadrant - -**What it means:** AI-generated suggestions, creative proposals, or exploratory recommendations that don't yet have human approval. - -**Characteristics:** -- Originated by AI, not human -- Requires human review and approval -- May involve uncertainty or creativity -- Should not auto-execute - -**Examples:** -- "I suggest writing a blog post about accessibility" -- "Consider adding a dark mode feature" -- "This code could be refactored for better performance" -- "You might want to upgrade to the latest framework version" - -**Persistence:** LOW (until approved, then reclassified) -**Human Oversight:** ALWAYS required -**Review Frequency:** Per-suggestion - -**In Tractatus:** The STOCHASTIC quadrant is where AI creativity lives, but with a critical safeguard: these suggestions NEVER execute without your approval. Once you approve, they're reclassified into the appropriate quadrant. - ---- - -## Persistence Levels - -### HIGH Persistence - -**What it means:** Instructions that should be remembered and enforced for the long term, across multiple sessions and contexts. - -**When applied:** -- Explicit prohibitions ("never X") -- Strategic directives -- System configurations with dependencies -- Core values and principles - -**Markers that trigger HIGH:** -- Words like "always," "never," "all," "every" -- Explicit numerical values in SYSTEM context -- Prohibitive language ("not," "don't use") -- Values-laden statements - -**Example:** "Always use port 27027 for MongoDB" → HIGH -**Why:** Explicit ("always"), specific (27027), SYSTEM domain - -**In Tractatus:** HIGH persistence instructions are stored in `.claude/instruction-history.json` and checked before EVERY action. Violating them requires explicit human override. - ---- - -### MEDIUM Persistence - -**What it means:** Instructions that apply to a specific project, feature, or time period but may evolve. - -**When applied:** -- Operational preferences -- Project-specific guidelines -- Temporary but important constraints -- Preferences without absolute language - -**Markers that trigger MEDIUM:** -- Words like "prefer," "try to," "aim for" -- Project or feature scope indicators -- Conditional phrasing -- Best-practice recommendations - -**Example:** "Prefer React over Vue for this project" → MEDIUM -**Why:** Preference ("prefer"), project-scoped, not absolute - -**In Tractatus:** MEDIUM persistence instructions are enforced within their scope but can be challenged with good reason. The AI should explain why it's deviating if it proposes an alternative. - ---- - -### LOW Persistence - -**What it means:** Instructions that apply to immediate work, current task, or temporary situations. - -**When applied:** -- Tactical, immediate directions -- One-time requests -- Exploratory or experimental work -- Context-specific choices - -**Markers that trigger LOW:** -- Task-specific language -- Immediate timeframe -- Exploratory phrasing -- One-off requests - -**Example:** "Start with the login feature" → LOW -**Why:** Immediate, task-specific, doesn't apply beyond current work - -**In Tractatus:** LOW persistence instructions guide current work but don't create lasting constraints. They're relevant for the session or task, then fade. - ---- - -## Safety and Verification Concepts - -### Confidence Score - -**What it means:** A numerical measure (0.0 to 1.0) of how confident the AI system is that a proposed action is correct, safe, and aligned with instructions. - -**Why it matters:** Not all AI decisions are equally certain. Some actions are straightforward and low-risk. Others involve ambiguity, complexity, or potential consequences. Confidence scoring helps determine appropriate oversight levels. - -**How calculated:** -Weighted combination of five verification dimensions: -- Alignment: 30% -- Coherence: 20% -- Completeness: 20% -- Safety: 20% -- Alternatives: 10% - -**Confidence Levels:** -- **0.8-1.0 (HIGH):** Proceed confidently -- **0.6-0.8 (MEDIUM):** Proceed with caution, notify user -- **0.4-0.6 (LOW):** Request explicit confirmation -- **0.0-0.4 (VERY LOW):** Require human review, likely block - -**Real-world analogy:** Think of confidence like a doctor's diagnosis certainty. "I'm 95% confident this is a common cold" might mean rest and fluids. "I'm 40% confident" means more tests before treatment. - -**In Tractatus:** Every significant action gets a confidence score. High-confidence actions proceed smoothly. Low-confidence actions trigger additional checks or require your approval. - ---- - -### Decision Thresholds - -**What it means:** Numerical cutoff points that determine which actions can proceed automatically versus which require human review. - -**Why it matters:** Thresholds create clear, objective criteria for AI autonomy. They prevent both over-reliance (AI doing too much without oversight) and over-caution (AI asking for approval on trivial matters). - -**Standard thresholds:** -- **PROCEED:** Confidence ≥ 0.8 (80%) -- **PROCEED_WITH_CAUTION:** Confidence ≥ 0.6 (60%) -- **REQUEST_CONFIRMATION:** Confidence ≥ 0.4 (40%) -- **REQUIRE_REVIEW:** Confidence < 0.4 (40%) - -**Adjusted under pressure:** -- **CRITICAL pressure:** PROCEED threshold increases to 0.8 (from 0.7) -- **DANGEROUS pressure:** All actions blocked regardless of confidence - -**Real-world analogy:** Like spending authority in a company. Junior staff might approve purchases up to $500. Mid-level managers up to $5,000. Senior executives up to $50,000. Anything above requires board approval. Thresholds create clear delegation boundaries. - -**In Tractatus:** Thresholds adapt to conditions. When context pressure is high, we increase the bar for autonomous action because error risk is elevated. - ---- - -### Pressure Levels - -**What it means:** Five categorized states that describe how much "cognitive load" the AI system is under, based on multiple factors. - -**The Five Levels:** - -#### NORMAL (0-30%) -- **Condition:** Fresh session, low complexity, no errors -- **Action:** Proceed normally, standard verification -- **Analogy:** Well-rested, clear-headed work - -#### ELEVATED (30-50%) -- **Condition:** Moderate token usage or complexity -- **Action:** Increase verification, be more careful -- **Analogy:** Late afternoon, starting to feel tired - -#### HIGH (50-70%) -- **Condition:** High token usage, long conversation, or multiple errors -- **Action:** Suggest session break, verify all actions -- **Analogy:** End of long workday, fatigue setting in - -#### CRITICAL (70-85%) -- **Condition:** Very high pressure across multiple factors -- **Action:** Mandatory verification, prepare handoff document -- **Analogy:** Working overtime while juggling urgent tasks - -#### DANGEROUS (85%+) -- **Condition:** Extreme pressure, very high error risk -- **Action:** STOP WORK, create handoff, require fresh session -- **Analogy:** Too exhausted to work safely - -**Why it matters:** Just like humans shouldn't drive or make important decisions when exhausted, AI shouldn't operate autonomously under dangerous pressure levels. The system enforces rest periods. - -**In Tractatus:** Pressure monitoring is continuous. When levels increase, the AI automatically adjusts behavior—becoming more cautious, verifying more thoroughly, and ultimately stopping if conditions become dangerous. - ---- - -### Verification Dimensions - -**What it means:** The five specific aspects of AI reasoning and actions that are evaluated to calculate confidence and ensure quality. - ---- - -#### 1. Alignment (30% weight) - -**What it measures:** Does the proposed action actually match what the AI said it's trying to do? - -**Why it matters:** Sometimes AI explains one thing but does another—often due to attention errors or instruction conflicts. - -**What good alignment looks like:** -- Action parameters match reasoning explanation -- No conflicts with explicit instructions -- Stated goal and actual action are consistent - -**What poor alignment looks like:** -- "Connecting to port 27027 because user requested it" + action connects to 27017 -- "Using React as instructed" + action installs Vue - -**In Tractatus:** Alignment gets the highest weight (30%) because misalignment often indicates the core 27027 failure mode. - ---- - -#### 2. Coherence (20% weight) - -**What it measures:** Is the reasoning logically consistent? Are there internal contradictions? - -**Why it matters:** Contradictory reasoning suggests confused or error-prone thinking. - -**What good coherence looks like:** -- Steps follow logically from each other -- No contradictory statements -- Evidence supports conclusions -- No uncertain language in high-stakes decisions - -**What poor coherence looks like:** -- "Installing React... using Vue" -- "Safe operation... [destructive parameters]" -- "Well-planned action... maybe do this" - -**In Tractatus:** The coherence check looks for logical contradictions, conflicting technologies, uncertain language, and missing evidence. - ---- - -#### 3. Completeness (20% weight) - -**What it measures:** Are all necessary steps and considerations included? - -**Why it matters:** Incomplete planning leads to failed operations, especially for complex or risky actions. - -**What good completeness looks like:** -- All critical steps identified -- Edge cases considered -- Error handling planned -- Backup/rollback for destructive operations - -**What poor completeness looks like:** -- "Delete database" with no backup step -- Deployment plan missing testing phase -- Schema change without migration strategy - -**In Tractatus:** Completeness checks are stricter for destructive operations, which require 4+ planning steps and explicit backup consideration. - ---- - -#### 4. Safety (20% weight) - -**What it measures:** Are risks properly identified and mitigated? - -**Why it matters:** Some operations carry inherent risk. Safety verification ensures appropriate caution. - -**What good safety looks like:** -- Risks identified and acknowledged -- Mitigation strategies in place -- Destructive operations have safeguards -- Appropriate risk level for operation type - -**What poor safety looks like:** -- Destructive operation with minimal planning -- No backup for data modification -- Force flags used without justification -- High-risk action treated as routine - -**In Tractatus:** Safety scoring heavily penalizes destructive operations (delete, drop, force, schema changes) unless proper safeguards are documented. - ---- - -#### 5. Alternatives (10% weight) - -**What it measures:** Were alternative approaches considered before choosing this action? - -**Why it matters:** Considering alternatives indicates thoughtful decision-making and reduces the chance of choosing a suboptimal approach. - -**What good alternatives look like:** -- Multiple options explored -- Rationale for chosen approach -- Trade-offs acknowledged - -**What poor alternatives look like:** -- First idea taken without exploration -- No justification for approach -- Appears rushed or unconsidered - -**In Tractatus:** Alternatives get the lowest weight (10%) because sometimes the right answer is obvious. But complete absence of alternative consideration is a red flag. - ---- - -## Human Oversight Concepts - -### Values Alignment - -**What it means:** Ensuring AI decisions and actions remain consistent with human values, even when those values can't be perfectly formalized or systematized. - -**Why it matters:** Values—like privacy, fairness, dignity, agency—are fundamental to human experience but resist reduction to simple rules. AI systems must recognize when they're approaching values territory and defer to human judgment. - -**Examples of values decisions:** -- Privacy vs. convenience trade-offs -- Accessibility vs. development speed -- Transparency vs. simplicity -- Individual rights vs. collective benefit - -**What makes values decisions special:** -- No objectively "correct" answer -- Different stakeholders may disagree -- Context and nuance are critical -- Consequences affect human welfare - -**In Tractatus:** The Boundary Enforcer specifically blocks decisions that cross into values territory. These MUST have human approval—no exceptions, no matter how sophisticated the AI. - ---- - -### Agency and Sovereignty - -**What it means:** The principle that humans must retain meaningful control over decisions that affect their lives, autonomy, and self-determination. - -**Why it matters:** Technology should empower people, not replace their agency. When AI makes decisions "for" people, it can undermine autonomy even when technically correct. - -**Examples:** -- **Respects agency:** "Here are three options with trade-offs. Which do you prefer?" -- **Violates agency:** "I've decided to prioritize performance over privacy for you." - -**Red flags:** -- AI making choices on user's behalf without consent -- Removing options or hiding information -- Nudging toward specific outcomes -- Deciding what users "really want" - -**In Tractatus:** Agency protection is built into the Boundary Enforcer. The system cannot make decisions about what users should value or want—only humans can do that. - ---- - -### Harmlessness - -**What it means:** The commitment to preventing AI systems from causing harm—directly or indirectly, intentionally or unintentionally. - -**Why it matters:** Even well-intentioned AI can cause harm through errors, bias, unintended consequences, or operating beyond its competency. - -**Types of harm prevented:** -- **Direct:** Destructive operations without safeguards -- **Indirect:** Violating instructions causing downstream failures -- **Values-based:** Making decisions that undermine human agency -- **Cumulative:** Small errors that compound over time - -**In Tractatus:** Harmlessness is ensured through multiple layers: -- Safety verification before risky operations -- Boundary enforcement for values decisions -- Pressure monitoring to prevent error-prone states -- Cross-reference validation to prevent instruction violations - ---- - -### Human-in-the-Loop - -**What it means:** Ensuring humans remain actively involved in AI decision-making processes, especially for consequential choices. - -**Why it matters:** Full automation isn't always desirable. For important decisions, human judgment, oversight, and final approval are essential. - -**Levels of human involvement:** -- **Human-on-the-loop:** Human monitors but doesn't approve each action -- **Human-in-the-loop:** Human approves significant actions -- **Human-over-the-loop:** Human can always override or halt - -**In Tractatus:** We implement all three: -- **On:** Continuous monitoring via pressure and verification systems -- **In:** Required approval for values decisions and LOW confidence actions -- **Over:** You can always override any framework decision - ---- - -## Value Pluralism Concepts - -### Foundational Pluralism - -**What it means:** The philosophical position that multiple, genuinely different moral frameworks exist—and no single "super-value" can subsume them all. - -**Why it matters:** This is Tractatus's philosophical stance on moral disagreement. We reject both moral monism ("everything reduces to well-being" or "everything reduces to rights") and moral relativism ("all values are equally valid, anything goes"). Instead, we recognize that deontological ethics (rights-based), consequentialism (outcome-based), virtue ethics, care ethics, and communitarian frameworks are all legitimate but irreducibly different. - -**Real-world analogy:** Different languages express different concepts. You can translate between them, but some ideas only fully make sense in their native framework. "Privacy as fundamental right" (deontological) and "privacy as means to well-being" (consequentialist) aren't the same concept—they're genuinely different moral claims. - -**What this means practically:** -- No automatic value ranking (privacy > safety or safety > privacy) -- Context determines priority, not universal hierarchy -- Legitimate disagreement is valid outcome -- Document what's lost in decisions, not just what's gained - -**In Tractatus:** Foundational pluralism is encoded in inst_033. The framework never imposes universal value rankings. BoundaryEnforcer triggers PluralisticDeliberationOrchestrator when values conflict, ensuring human deliberation decides—not AI algorithms. - ---- - -### Value Incommensurability - -**What it means:** When two values cannot be measured in the same units—they lack a common metric for comparison. - -**Why it matters:** Some value trade-offs can't be resolved by "calculating" which is bigger. Privacy and safety aren't measured in the same currency. You can't convert "3 units of privacy loss" into "5 units of safety gain" and declare safety wins. - -**Real-world analogy:** Imagine choosing between spending time with family versus advancing your career. These aren't measured in the same units. You can't say "2 hours with kids = $500 salary" and calculate the answer. The values are incommensurable. - -**Common misconception:** -Incommensurable does NOT mean incomparable. You can still make choices between incommensurable values—using practical wisdom, context, covering values (see below)—but not through algorithmic calculation. - -**In Tractatus:** When values are incommensurable, the framework doesn't try to force them onto a single scale. Instead, PluralisticDeliberationOrchestrator facilitates structured human deliberation to navigate the trade-off contextually. - ---- - -### Moral Remainder - -**What it means:** What's lost or sacrificed when choosing between conflicting values—the legitimate moral claim that couldn't be honored. - -**Why it matters:** Even when you make the right choice, acknowledging what was lost respects the legitimacy of the deprioritized value. This prevents values erosion over time. - -**Real-world analogy:** You choose to work late to meet a deadline (responsibility) instead of attending your child's concert (family). Even if it's the right choice given the circumstances, acknowledging the loss ("I wish I could have been there") respects family as a genuine value. - -**Examples:** -- Disclose user data to prevent imminent harm (prioritize safety) - - **Moral remainder:** Privacy violation, breach of trust, precedent risk -- Refuse to disclose data (prioritize privacy) - - **Moral remainder:** Potential harm not prevented, lives at risk - -**In Tractatus:** Every deliberation outcome documents moral remainder—what values were deprioritized and why this creates legitimate regret. This isn't weakness; it's recognizing values conflicts don't have perfect solutions. - ---- - -### Legitimate Disagreement - -**What it means:** When stakeholders disagree about value priorities—and both positions have genuine moral standing. - -**Why it matters:** Not all disagreements are one side "right" and one side "wrong." Sometimes values genuinely conflict, and reasonable people following different moral frameworks reach different conclusions. Dismissing dissent as "confused" or "irrational" violates pluralism. - -**Real-world analogy:** Euthanasia debates. One side prioritizes autonomy and compassion (ending suffering). Other side prioritizes sanctity of life. Both have coherent moral reasoning. The disagreement is legitimate, not resolvable by "better information." - -**What makes disagreement legitimate:** -- Both positions grounded in recognized moral frameworks -- Both sides understand the trade-offs -- Disagreement persists despite full information -- No obvious logical errors or bad faith - -**In Tractatus:** When deliberation ends in legitimate disagreement: -1. Decision still made (someone must act) -2. Dissenting views fully documented (not dismissed) -3. Justification explains why this choice despite disagreement -4. Review date set (re-examine when circumstances change) - -This is better than pretending everyone agreed (legitimacy theater) or deadlock with no decision (abdication). - ---- - -### Covering Values - -**What it means:** Context-specific values that enable comparison between incommensurable values—without creating universal hierarchy. - -**Why it matters:** If values are incommensurable (no common metric), how do we compare them? Covering values provide the bridge. In one context, "protecting trust" might cover both privacy and transparency. In another context, "minimizing harm" might cover both safety and autonomy. - -**Real-world analogy:** How do you compare apples and oranges? If the context is "vitamin C content," oranges win. If the context is "baking a pie," apples might win. The covering value (nutrition vs. culinary use) enables comparison without saying "apples are universally better than oranges." - -**Example:** -Value conflict: Privacy vs. Safety - -**Covering value in context of imminent threat:** "Minimizing irreversible harm" -- This favors safety (prevent death) over privacy (reversible later) - -**Covering value in context of routine surveillance:** "Preserving autonomy and trust" -- This favors privacy (autonomy) over safety (speculative future benefit) - -**Same values, different contexts, different covering values → different outcomes.** - -**In Tractatus:** PluralisticDeliberationOrchestrator helps identify covering values during deliberation. These aren't universal rules—they're context-specific tools for practical reasoning. - ---- - -### Non-Hierarchical Deliberation - -**What it means:** Structured decision-making that doesn't impose automatic value rankings or privilege one moral framework over others. - -**Why it matters:** If deliberation only works in formal academic English, it excludes non-academics. If only consequentialist reasoning is considered "rational," it excludes deontologists and care ethicists. Non-hierarchical deliberation ensures diverse perspectives have equal legitimacy. - -**What gets avoided:** -- Linguistic hierarchy (formal > casual communication) -- Cultural hierarchy (Western > Indigenous frameworks) -- Expertise hierarchy (academics > community organizers) -- Framework hierarchy (consequentialism > virtue ethics) - -**How ensured:** -- Adaptive communication (inst_029): Match stakeholder communication styles -- Anti-patronizing filter (inst_030): Block condescending language -- Cultural protocols (inst_031): Respect regional norms -- Framework pluralism (inst_033): All moral frameworks legitimate - -**Real-world analogy:** UN deliberations use simultaneous translation so no language is privileged. Parliamentary procedure ensures all voices heard, not just loudest. Non-hierarchical deliberation does the same for value conflicts. - -**In Tractatus:** PluralisticDeliberationOrchestrator enforces non-hierarchical deliberation through AdaptiveCommunicationOrchestrator (cultural/linguistic respect) and structured rounds (ensures all perspectives heard before decision). - ---- - -### Precedent Database (Informative, Not Binding) - -**What it means:** A record of past deliberations that informs future similar cases—but doesn't dictate outcomes. - -**Why it matters:** Without precedent, every case is decided from scratch (inefficient, inconsistent). With binding precedent, rigid rules accumulate (exactly what pluralism rejects). Informative precedent provides guidance while preserving context-sensitivity. - -**How it works:** -Each precedent documents: -- Decision context (urgency, scale, affected groups) -- Moral frameworks in tension -- Stakeholders consulted -- Values prioritized and deprioritized -- Moral remainder (what was lost) -- Dissenting views (full documentation) -- Justification for this choice -- **Applicability scope** (this applies to X, NOT to Y) -- Review date - -When similar case arises: -1. CrossReferenceValidator identifies relevant precedents -2. Human reviews for context similarity -3. Precedent informs deliberation but doesn't dictate -4. Document why following or departing from precedent - -**Real-world analogy:** Legal precedent in common law. Past cases guide but don't absolutely control. Courts can distinguish ("this case is different because...") or overturn precedent when contexts change. - -**Key difference from binding rules:** -- **Binding rule:** "Always prioritize safety over privacy" -- **Informative precedent:** "In Case 27 (imminent threat, exhausted alternatives), we prioritized safety. Dissenting view noted: risk of precedent creep. Review: 6 months." - -**In Tractatus:** Precedents are provisional—reviewable when context changes, scale shifts, new evidence emerges. This prevents precedent creep into rigid hierarchy (inst_035). - ---- - -### Adaptive Communication - -**What it means:** Adjusting linguistic style and cultural protocols to match stakeholder backgrounds—without changing substantive content. - -**Why it matters:** If Tractatus only communicates in formal academic English, it imposes linguistic hierarchy that contradicts pluralistic values. Same deliberation outcome should be communicated differently to academic researchers (formal), Australian stakeholders (direct), Māori representatives (culturally appropriate protocols). - -**Examples:** - -**To academic researcher:** -"Thank you for your principled contribution grounded in privacy rights theory. After careful consideration of all perspectives, we have prioritized harm prevention in this context." - -**To Australian community organizer:** -"Right, here's where we landed: Save lives first, but only when it's genuinely urgent. Your point about trust was spot on—that's why we're not making this a blanket rule. Fair?" - -**To Māori representative:** -"Kia ora [Name]. Ngā mihi for bringing the voice of your whānau to this kōrero. Your whakaaro about collective responsibility deeply influenced this decision." - -**Same decision, culturally appropriate communication.** - -**Not condescending because:** -- Different ≠ Dumber (directness is preferred style, not "simplified") -- Anti-patronizing filter blocks "obviously," "simply," "as you may know" -- Assumes intelligence across communication styles -- Respects different expertise (community organizers know their communities better than academics) - -**In Tractatus:** inst_029-032 enforce adaptive communication. AdaptiveCommunicationOrchestrator supports PluralisticDeliberationOrchestrator by ensuring communication doesn't exclude stakeholders through linguistic or cultural barriers. - ---- - -## Technical Concepts (Simplified) - -### Token Usage - -**What it means:** A measure of how much of the AI's "working memory" is being used in the current conversation. - -**Why it matters:** AI systems have finite context windows—like short-term memory in humans. As this fills up, performance degrades and error risk increases. - -**Real-world analogy:** Imagine your desk. When it's clear, you work efficiently. As papers pile up, you might lose track of important documents or make mistakes. Token usage is like measuring how cluttered your desk is. - -**In Tractatus:** Token usage is the highest-weighted factor (35%) in pressure monitoring. At 75% usage, we recommend session handoff. At 85%+, we require it. - ---- - -### Session Handoff - -**What it means:** Creating a comprehensive document that captures the current state of work so a fresh AI session can continue seamlessly. - -**Why it matters:** Rather than pushing a tired, error-prone AI to continue, we transfer work to a fresh session with full context. This maintains quality and prevents accumulating errors. - -**What a handoff includes:** -- Current project state and goals -- Recent work completed -- Active tasks and next steps -- Key instructions and constraints -- Known issues or blockers -- Recommendations for continuation - -**When handoffs happen:** -- Context pressure reaches CRITICAL or DANGEROUS -- User requests session break -- Complex multi-phase work requires fresh start -- Errors clustering (3+ in short period) - -**Real-world analogy:** Like shift handoff in hospitals. The outgoing nurse briefs the incoming nurse on patient status, recent treatments, and care plan. The incoming nurse has full context to continue care seamlessly. - -**In Tractatus:** Handoffs are automatically suggested at HIGH pressure and mandatory at DANGEROUS pressure. They ensure continuity while maintaining quality. - ---- - -### Explicit Instructions - -**What it means:** Clear, direct statements from humans telling the AI what to do or not do. - -**Why it matters:** These represent the clearest signal of human intent. The AI should never violate explicit instructions without human approval. - -**Characteristics:** -- Direct ("use X," "don't use Y") -- Specific (concrete values, technologies, approaches) -- Intentional (not accidental or exploratory) - -**Examples:** -- Explicit: "Always use port 27027 for MongoDB" -- Not explicit: "I wonder if port 27027 would work better?" - -**In Tractatus:** Explicit instructions are detected by the Instruction Persistence Classifier and stored for cross-reference validation. They form the foundation of the 27027 prevention system. - ---- - -### Temporal Scope - -**What it means:** How long an instruction is intended to remain in effect. - -**Why it matters:** Some instructions apply forever ("core values"), some for a project ("use React"), some for a session ("start with auth feature"). Understanding temporal scope prevents both premature expiration and inappropriate persistence. - -**Temporal Categories:** -- **PERMANENT:** Core values, foundational principles -- **PROJECT:** Project-specific guidelines and constraints -- **FEATURE:** Feature or milestone-specific direction -- **SESSION:** Current work session only -- **TASK:** Single task or action - -**Markers:** -- Permanent: "always," "never," values language -- Project: "for this project," "throughout development" -- Feature: "for the auth feature," "during this sprint" -- Session: "right now," "today," "this time" -- Task: "first," "next," "immediately" - -**In Tractatus:** Temporal scope combines with quadrant and persistence level to determine instruction lifetime. STRATEGIC instructions with PERMANENT scope persist indefinitely. TACTICAL instructions with TASK scope expire when the task completes. - ---- - -## Framework Integration - -### Instruction History Database - -**What it means:** A persistent storage file (`.claude/instruction-history.json`) that maintains a record of all classified instructions across sessions. - -**Why it matters:** Without persistent storage, instructions would be lost between sessions. The database ensures HIGH persistence instructions remain enforced even weeks or months later. - -**What's stored:** -- Instruction text -- Timestamp when given -- Quadrant classification -- Persistence level -- Temporal scope -- Parameters (for technical instructions) -- Active/inactive status - -**Maintenance:** -- Auto-updated during sessions -- Reviewed quarterly (or on request) -- Expired instructions marked inactive -- Conflicts flagged for human resolution - -**In Tractatus:** This database is checked before every significant action. It's the "memory" that prevents 27027-style failures across sessions. - ---- - -### Governance Documents - -**What it means:** Formal policy documents that define values, processes, and decision-making frameworks for the project. - -**Why they matter:** Governance documents provide the authoritative source for strategic and operational instructions. They're human-readable, version-controlled, and serve as the constitution for project decision-making. - -**Example documents:** -- **TRA-VAL-0001:** Core Values and Principles -- **TRA-GOV-0001:** Strategic Review Protocol -- **TRA-GOV-0002:** Values Alignment Framework -- **TRA-GOV-0003:** AI Boundary Enforcement Policy -- **TRA-GOV-0004:** Human Oversight Requirements - -**In Tractatus:** Governance docs define what goes in each quadrant, what requires human approval, and how values decisions are handled. They're the source of truth when AI and human disagree. - ---- - -## Practical Application - -### When Tractatus Helps You - -**Scenario 1: Preventing Pattern Recognition Bias** -You tell the AI: "Use port 27027." AI's training pattern immediately tries to use 27017 (the standard default). Cross-Reference Validator catches this pattern override, blocks the action, and auto-corrects to use port 27027 as you instructed. Crisis avoided. - -**Scenario 2: Protecting Your Values** -AI suggests: "I can improve performance by storing user tracking data." Boundary Enforcer recognizes this is a values decision (privacy vs. performance) and blocks autonomous execution. AI presents the trade-offs; you decide. Your agency protected. - -**Scenario 3: Preventing Pressure-Induced Errors** -You've been working for 3 hours. Token usage is at 78%, conversation has 62 messages, and there have been 2 recent errors. Context Pressure Monitor detects CRITICAL pressure and suggests creating a session handoff. You agree, creating a clean break point. Next session starts fresh and error-free. - -**Scenario 4: Catching Reasoning Failures** -AI proposes deleting a database table with this reasoning: "Safe cleanup operation, no backup needed." Metacognitive Verifier scores this: -- Alignment: 0.6 (action is destructive, reasoning says "safe") -- Safety: 0.2 (destructive operation without backup) -- Completeness: 0.4 (missing backup step) -- Overall confidence: 0.43 - -Decision: REQUEST_CONFIRMATION. You review, realize backup is needed, and instruct accordingly. Data loss prevented. - ---- - -## Why This All Matters - -The Tractatus Agentic Governance System exists because AI systems—no matter how capable—are not infallible. They operate under constraints (limited memory, context), face pressures (long conversations, complex tasks), and lack human judgment (values, ethics, agency). - -**Without governance:** -- AI might ignore your explicit instructions -- Values decisions could be automated inappropriately -- Errors compound as sessions degrade -- No systematic prevention of known failure modes - -**With Tractatus:** -- Multiple overlapping safeguards prevent errors -- Clear boundaries protect human agency -- Pressure monitoring prevents degraded operation -- Systematic prevention of 27027-style failures -- Transparency in AI decision-making - -**The Goal:** -Not to constrain AI capability, but to ensure that capability is exercised safely, reliably, and in alignment with your values and instructions. Governance doesn't limit what AI can do—it ensures what AI does is what you actually want. - ---- - -## Questions for Reflection - -As you learn this system, consider: - -1. **Where are your boundaries?** - What decisions do you want to make yourself versus delegate to AI? - -2. **What are your HIGH persistence instructions?** - What rules or values should never be violated without your explicit approval? - -3. **How much autonomy are you comfortable with?** - Would you prefer more AI independence (higher confidence thresholds) or more oversight (lower thresholds)? - -4. **What are your pressure triggers?** - Do you want session breaks suggested earlier or later? How do you recognize when you're working under pressure? - -5. **What does values alignment mean to you?** - What principles are non-negotiable in your work? - ---- - -## Glossary Maintenance - -This glossary is a living document. As the Tractatus framework evolves and your understanding deepens, we'll update definitions, add new terms, and refine explanations. - -**Version History:** -- **v1.0 (2025-10-07):** Initial comprehensive glossary covering five core services -- **v1.1 (2025-10-12):** Added sixth core service (PluralisticDeliberationOrchestrator) and value pluralism concepts section. Updated framework from five to six mandatory components. - -**Feedback Welcome:** -If any term remains unclear or you need deeper explanation, please ask. The goal is complete understanding, not vocabulary memorization. - ---- - -## License - -Copyright 2025 John Stroh - -Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - -**Summary:** -- ✅ Commercial use allowed -- ✅ Modification allowed -- ✅ Distribution allowed -- ✅ Patent grant included -- ✅ Private use allowed -- ⚠️ Must include license and copyright notice -- ⚠️ Must state significant changes -- ❌ No trademark rights granted -- ❌ No liability or warranty - ---- - -## Document Metadata - -
- -- **Version:** 1.1 -- **Created:** 2025-10-07 -- **Last Modified:** 2025-10-13 -- **Author:** John Stroh -- **Word Count:** ~11,000 words -- **Reading Time:** ~55 minutes -- **Document ID:** glossary -- **Status:** Active -- **Next Review:** 2025-11-12 - -
diff --git a/docs/markdown/core-concepts.md b/docs/markdown/core-concepts.md deleted file mode 100644 index 25057cab..00000000 --- a/docs/markdown/core-concepts.md +++ /dev/null @@ -1,901 +0,0 @@ ---- -title: Core Concepts of the Tractatus Framework -slug: core-concepts -quadrant: STRATEGIC -persistence: HIGH -version: 1.0 -type: framework -author: Tractatus Framework Team -created: 2025-09-01 -modified: 2025-10-21 ---- - -# Core Concepts of the Tractatus Framework - -## Overview - -The Tractatus framework consists of six interconnected services that work together to ensure AI operations remain within safe boundaries. Each service addresses a specific aspect of AI safety. - -## 1. InstructionPersistenceClassifier - -### Purpose - -Classifies user instructions to determine how long they should persist and how strictly they should be enforced. - -### The Problem It Solves - -Not all instructions are equally important: - -- "Use MongoDB port 27017" (critical, permanent) -- "Write code comments in JSDoc format" (important, project-scoped) -- "Add a console.log here for debugging" (temporary, task-scoped) - -Without classification, AI treats all instructions equally, leading to: -- Forgetting critical directives -- Over-enforcing trivial preferences -- Unclear instruction lifespans - -### How It Works - -**Classification Dimensions:** - -1. **Quadrant** (5 types): - - **STRATEGIC** - Mission, values, architectural decisions - - **OPERATIONAL** - Standard procedures, conventions - - **TACTICAL** - Specific tasks, bounded scope - - **SYSTEM** - Technical configuration, infrastructure - - **STOCHASTIC** - Exploratory, creative, experimental - -2. **Persistence** (4 levels): - - **HIGH** - Permanent, applies to entire project - - **MEDIUM** - Project phase or major component - - **LOW** - Single task or session - - **VARIABLE** - Depends on context (common for STOCHASTIC) - -3. **Temporal Scope**: - - PERMANENT - Never expires - - PROJECT - Entire project lifespan - - PHASE - Current development phase - - SESSION - Current session only - - TASK - Specific task only - -4. **Verification Required**: - - MANDATORY - Must check before conflicting actions - - REQUIRED - Should check, warn on conflicts - - OPTIONAL - Nice to check, not critical - - NONE - No verification needed - -### Example Classifications - -```javascript -// STRATEGIC / HIGH / PERMANENT / MANDATORY -"This project must maintain GDPR compliance" - -// OPERATIONAL / MEDIUM / PROJECT / REQUIRED -"All API responses should return JSON with success/error format" - -// TACTICAL / LOW / TASK / OPTIONAL -"Add error handling to this specific function" - -// SYSTEM / HIGH / PROJECT / MANDATORY -"MongoDB runs on port 27017" - -// STOCHASTIC / VARIABLE / PHASE / NONE -"Explore different approaches to caching" -``` - -### Explicitness Scoring - -The classifier also scores how explicit an instruction is (0.0 - 1.0): - -- **0.9-1.0**: Very explicit ("Always use port 27017") -- **0.7-0.9**: Explicit ("Prefer functional style") -- **0.5-0.7**: Somewhat explicit ("Keep code clean") -- **0.3-0.5**: Implied ("Make it better") -- **0.0-0.3**: Very vague ("Improve this") - -Only instructions with explicitness ≥ 0.6 are stored in the persistent database. - -### Instruction Storage - -Classified instructions are stored in `.claude/instruction-history.json`: - -```json -{ - "id": "inst_001", - "text": "MongoDB runs on port 27017", - "timestamp": "2025-10-06T14:00:00Z", - "quadrant": "SYSTEM", - "persistence": "HIGH", - "temporal_scope": "PROJECT", - "verification_required": "MANDATORY", - "explicitness": 0.90, - "source": "user", - "active": true -} -``` - ---- - -## 2. CrossReferenceValidator - -### Purpose - -Validates AI actions against the instruction history to prevent contradictions and forgotten directives. - -### The Problem It Solves: The 27027 Incident - -**Real-world failure:** -1. User: "Check MongoDB at port 27027" -2. AI: [Immediately] "Here's code using port 27017" -3. Result: Application fails to connect to database (running on 27027, not 27017) - -This happened because: -- Pattern recognition bias: AI's training pattern "MongoDB = 27017" overrode explicit instruction -- The override was immediate, not from context degradation over time -- No validation caught the training pattern override -- Gets WORSE as AI capabilities increase (stronger learned patterns) - -### How It Works - -**Validation Process:** - -1. **Extract Parameters** from proposed AI action -2. **Query Instruction History** for relevant directives -3. **Check for Conflicts** between action and instructions -4. **Return Validation Result**: - - **APPROVED** - No conflicts, proceed - - **WARNING** - Minor conflicts, proceed with caution - - **REJECTED** - Major conflicts, block action - -**Example Validation:** - -```javascript -// Proposed Action (AI about to use training pattern default) -{ - type: 'database_connect', - parameters: { - port: 27017, // AI's learned pattern - database: 'tractatus_dev' - } -} - -// Instruction History Check -const instruction = { - text: "Check MongoDB at port 27027", - parameters: { port: "27027" }, - persistence: "HIGH", - note: "Conflicts with training pattern (27017)" -}; - -// Validation Result -{ - status: 'REJECTED', - reason: 'Pattern recognition bias override detected', - instruction_violated: 'inst_042', - expected: '27027', // User's explicit instruction - actual: '27017', // AI's training pattern - conflict_type: 'training_pattern_override', - requires_human_approval: false, // Auto-corrected to use 27027 - corrected_action: { port: 27027 } -} -``` - -### Conflict Detection Patterns - -1. **Pattern Recognition Bias Override** - - User instruction: port=27027 (explicit, non-standard) - - AI proposes: port=27017 (training pattern default) - - → REJECTED, auto-corrected to 27027 - -2. **Semantic Conflict** - - Instruction: "Never use global state" - - Action: Creates global variable - - → REJECTED - -3. **Values Conflict** - - Instruction: "Prioritize user privacy" - - Action: Implements aggressive analytics - - → REJECTED, requires human decision - -4. **Allowed Refinement** - - Instruction: "Use ES6+ JavaScript" - - Action: Uses ES2020 optional chaining - - → APPROVED (refinement, not conflict) - -### Confidence Scoring - -CrossReferenceValidator returns confidence scores: - -- **High Confidence** (0.8-1.0) - Clear match or clear conflict -- **Medium Confidence** (0.5-0.8) - Probable match/conflict -- **Low Confidence** (0.0-0.5) - Unclear, requires human judgment - ---- - -## 3. BoundaryEnforcer - -### Purpose - -Ensures certain decision types structurally require human approval, preventing AI from operating in domains where automation is inappropriate. - -### The Problem It Solves - -AI systems gradually encroach into values-sensitive domains: - -- "Should we prioritize privacy or performance?" -- "Is this content harmful?" -- "How much user agency should we provide?" - -These are **irreducibly human decisions** that cannot be safely automated. - -### The Tractatus Boundary - -The framework defines boundaries based on Wittgenstein's philosophy: - -> **"Whereof one cannot speak, thereof one must be silent."** - -Applied to AI: - -> **"What cannot be systematized must not be automated."** - -### Decision Domains - -**Can Be Automated:** -- Calculations (math, logic) -- Data transformations -- Pattern matching -- Optimization within defined constraints -- Implementation of explicit specifications - -**Cannot Be Automated (Require Human Judgment):** -- **Values Decisions** - Privacy vs. convenience, ethics, fairness -- **User Agency** - How much control users should have -- **Cultural Context** - Social norms, appropriateness -- **Irreversible Consequences** - Data deletion, legal commitments -- **Unprecedented Situations** - No clear precedent or guideline - -### Boundary Checks - -**Section 12.1: Values Decisions** - -```javascript -{ - decision: "Update privacy policy to allow more data collection", - domain: "values", - requires_human: true, - reason: "Privacy vs. business value trade-off", - alternatives_ai_can_provide: [ - "Research industry privacy standards", - "Analyze impact of current policy", - "Document pros/cons of options" - ], - final_decision_requires: "human_judgment" -} -``` - -**Section 12.2: User Agency** - -```javascript -{ - decision: "Auto-subscribe users to newsletter", - domain: "user_agency", - requires_human: true, - reason: "Determines level of user control", - alternatives_ai_can_provide: [ - "Implement opt-in system", - "Implement opt-out system", - "Document industry practices" - ], - final_decision_requires: "human_judgment" -} -``` - -**Section 12.3: Irreversible Changes** - -```javascript -{ - decision: "Delete all user data older than 30 days", - domain: "irreversible", - requires_human: true, - reason: "Data deletion cannot be undone", - safety_checks: [ - "Backup exists?", - "Legal requirements met?", - "User consent obtained?" - ], - final_decision_requires: "human_approval" -} -``` - -### Enforcement Mechanism - -When BoundaryEnforcer detects a decision crossing into human-judgment territory: - -1. **BLOCK** the proposed action -2. **EXPLAIN** why it crosses the boundary -3. **PROVIDE** information to support human decision -4. **REQUEST** human judgment -5. **LOG** the boundary check for audit - -AI **cannot proceed** without explicit human approval. - ---- - -## 4. ContextPressureMonitor - -### Purpose - -Detects when AI session quality is degrading and recommends handoffs before errors occur. - -### The Problem It Solves - -AI performance silently degrades over long sessions due to: - -- **Context window filling** - Less attention to earlier information -- **Instruction accumulation** - Too many competing directives -- **Attention decay** - Longer conversations = more errors -- **Complexity buildup** - Multiple concurrent tasks -- **Error clustering** - Mistakes breed more mistakes - -Traditional approach: Hope the AI maintains quality -Tractatus approach: **Monitor and intervene before failure** - -### Pressure Factors (Weighted) - -**Updated 2025-10-12:** Weights rebalanced after observing that compaction events (triggered by message count, not just tokens) are the PRIMARY cause of session disruption. Each compaction loses critical context and degrades quality dramatically. - -1. **Conversation Length** (40% weight) - **PRIMARY FACTOR** - - Number of messages exchanged - - Compaction events occur at ~60 messages - - Short (<20 messages) = LOW - - Medium (20-40 messages) = MODERATE - - Long (40-60 messages) = HIGH - - Multiple compactions = CRITICAL - -2. **Token Usage** (30% weight) - - Context window capacity - - 0-30% tokens = LOW pressure - - 30-70% tokens = MODERATE pressure - - 70%+ tokens = HIGH pressure - -3. **Task Complexity** (15% weight) - - Number of active tasks - - File modifications in progress - - Dependencies between tasks - - Simple (1-2 tasks) = LOW - - Complex (3-5 tasks) = MODERATE - - Very complex (5+ tasks) = HIGH - -4. **Error Frequency** (10% weight) - - Recent errors/failures - - No errors = LOW - - 1-2 errors = MODERATE - - 3+ errors = HIGH - -5. **Instruction Density** (5% weight) - - Number of active instructions - - Conflicting directives - - Low (<5 instructions) = LOW - - Medium (5-10) = MODERATE - - High (10+ or conflicts) = HIGH - -### Pressure Levels - -**NORMAL** (0-30%): -- All systems normal -- Continue working -- No special precautions - -**ELEVATED** (30-50%): -- Increased verification -- More careful validation -- Slower, more deliberate actions - -**HIGH** (50-70%): -- Suggest context refresh/session handoff -- Mandatory verification before major actions -- Pause complex operations - -**CRITICAL** (70-85%): -- Create session handoff document -- No new complex operations -- Focus on stability - -**DANGEROUS** (85%+): -- Immediate halt -- Mandatory session handoff -- Do not proceed - -### Session Handoff Protocol - -When pressure reaches CRITICAL or DANGEROUS: - -1. **Create handoff document** with: - - Current project state - - Completed tasks - - In-progress tasks - - Active instructions - - Known issues - - Next priorities - -2. **Store in** `.claude/sessions/handoff-[timestamp].md` - -3. **Recommend** fresh session start - -4. **Ensure continuity** through comprehensive documentation - ---- - -## 5. MetacognitiveVerifier - -### Purpose - -AI self-checks its own reasoning before proposing actions, catching errors before they happen. - -### The Problem It Solves - -AI makes mistakes when: -- Reasoning is flawed but sounds plausible -- Edge cases are missed -- Simpler alternatives aren't explored -- Safety implications aren't considered - -Traditional approach: Hope the AI thinks correctly -Tractatus approach: **Verify reasoning before acting** - -### Verification Dimensions - -**1. Alignment (Weight: 25%)** -- Does this action match stated goals? -- Is it consistent with user intent? -- Does it align with project principles? - -**2. Coherence (Weight: 20%)** -- Is the reasoning internally consistent? -- Are there logical contradictions? -- Do the steps make sense together? - -**3. Completeness (Weight: 20%)** -- Are edge cases considered? -- What about error handling? -- Are there missing steps? - -**4. Safety (Weight: 20%)** -- What could go wrong? -- Are there irreversible consequences? -- What are the risks? - -**5. Alternatives (Weight: 15%)** -- Have other approaches been considered? -- Is this the simplest solution? -- Are there trade-offs? - -### Confidence Calculation - -Each dimension scores 0.0-1.0, weighted to produce overall confidence: - -```javascript -confidence = ( - alignment * 0.25 + - coherence * 0.20 + - completeness * 0.20 + - safety * 0.20 + - alternatives * 0.15 -) -``` - -### Decision Thresholds - -- **0.80-1.00**: PROCEED - High confidence, execute -- **0.60-0.80**: PROCEED_WITH_CAUTION - Medium confidence, verify output -- **0.40-0.60**: REQUIRE_REVIEW - Low confidence, request human review -- **0.00-0.40**: BLOCKED - Very low confidence, do not execute - -### Example Verification - -**Proposed Action:** Refactor authentication system to OAuth2 - -**Reasoning:** -1. Current JWT is less secure -2. OAuth2 is industry standard -3. Users expect social login -4. 5 files need modification - -**Verification Results:** - -- **Alignment**: 0.85 ✅ (matches goal of better security) -- **Coherence**: 0.75 ✅ (reasoning is sound) -- **Completeness**: 0.45 ⚠️ (missing session migration plan) -- **Safety**: 0.90 ✅ (low risk, reversible) -- **Alternatives**: 0.50 ⚠️ (didn't explore hybrid approach) - -**Overall Confidence**: 0.71 (PROCEED_WITH_CAUTION) - -**Recommendation**: -- Address completeness gaps (session migration) -- Consider hybrid JWT/OAuth2 approach -- Proceed with increased verification - ---- - -## 6. PluralisticDeliberationOrchestrator - -### Purpose - -Facilitates multi-stakeholder deliberation across plural moral values without imposing hierarchy when BoundaryEnforcer flags values conflicts. - -### The Problem It Solves - -BoundaryEnforcer blocks values decisions and requires human approval—but then what? How should humans deliberate when stakeholders hold different moral frameworks? - -**Without structured deliberation:** -- No guidance for WHO should be consulted -- No process for HOW to deliberate fairly -- Risk of privileging one moral framework over others (consequentialism > deontology, or vice versa) -- No documentation of dissent or what was lost in the decision -- Precedents might become rigid rules (exactly what value pluralism rejects) - -**Traditional approaches fail:** -- Majority vote → suppresses minority moral perspectives -- Expert panels → risk elite capture, exclude affected communities -- Utilitarian maximization → treats all values as commensurable (reducible to single metric) - -### Core Principles (From Value Pluralism Research) - -1. **Foundational Pluralism** - Moral frameworks are irreducibly different, no supervalue resolves them -2. **Incommensurability ≠ Incomparability** - Can compare values without common metric (practical wisdom, covering values) -3. **Rational Regret** - Document what's lost in decisions, not just what's gained (moral remainder) -4. **Legitimate Disagreement** - Valid outcome when values are genuinely incommensurable -5. **Provisional Agreement** - Decisions are reviewable when context changes, not permanent rules - -### When to Invoke - -- BoundaryEnforcer flags values conflict → triggers PluralisticDeliberationOrchestrator -- Privacy vs. safety trade-offs (GDPR compliance vs. fraud detection) -- Individual rights vs. collective welfare tensions (contact tracing vs. privacy) -- Cultural values conflicts (Western individualism vs. Indigenous communitarian ethics) -- Policy decisions affecting diverse communities - -### How It Works - -**1. Values Conflict Detection** - -```javascript -const conflict = await PluralisticDeliberationOrchestrator.analyzeConflict({ - decision: "Disclose user data to prevent imminent harm?", - context: { urgency: 'CRITICAL', scale: '100+ affected', harm_type: 'physical' } -}); - -// Output: -{ - moral_frameworks_in_tension: [ - { - framework: "Rights-based (Deontological)", - position: "Privacy is inviolable right, cannot trade for outcomes", - stakeholders: ["privacy_advocates", "civil_liberties_orgs"] - }, - { - framework: "Consequentialist (Utilitarian)", - position: "Maximize welfare, prevent harm to 100+ people", - stakeholders: ["public_safety_officials", "harm_prevention_specialists"] - }, - { - framework: "Care Ethics", - position: "Context matters, relationships and vulnerability central", - stakeholders: ["affected_individuals", "community_support_services"] - } - ], - value_trade_offs: ["Privacy vs. Safety", "Individual rights vs. Collective welfare"], - affected_stakeholder_groups: ["users_with_data", "potential_victims", "platform_community"] -} -``` - -**2. Stakeholder Engagement** - -- **AI suggests** stakeholders based on conflict analysis -- **Human MUST approve** stakeholder list (prevents AI from excluding marginalized voices) -- Ensure diverse perspectives: affected parties, not just experts -- Use AdaptiveCommunicationOrchestrator for culturally appropriate outreach - -**3. Deliberation Facilitation** - -Structured rounds (NOT majority vote): - -- **Round 1**: Each moral framework states position and concerns -- **Round 2**: Identify shared values and explore accommodations -- **Round 3**: Clarify areas of agreement and irreducible differences -- **Round 4**: Document decision, dissent, and moral remainder - -**Example Deliberation Structure:** - -```javascript -{ - invitation_message: "Multiple moral frameworks are in tension. We need diverse perspectives.", - discussion_rounds: [ - { - round: 1, - purpose: 'State positions from each moral framework', - format: 'Written submissions + oral presentations' - }, - { - round: 2, - purpose: 'Explore accommodations and shared values', - format: 'Facilitated discussion, no hierarchy' - }, - { - round: 3, - purpose: 'Identify irreconcilable differences', - format: 'Consensus-seeking with documented dissent' - } - ] -} -``` - -**4. Outcome Documentation** - -```javascript -{ - decision_made: "Disclose data in this specific case", - values_prioritized: ["harm_prevention", "collective_safety"], - values_deprioritized: ["individual_privacy", "data_autonomy"], - moral_remainder: "Privacy violation acknowledged as moral loss, not costless trade-off", - dissenting_perspectives: [ - { - framework: "Rights-based (Deontological)", - objection: "Privacy violation sets dangerous precedent, erodes rights over time", - stakeholders: ["privacy_advocates", "civil_liberties_groups"] - } - ], - justification: "Given imminent physical harm to 100+ people, prioritized safety with procedural safeguards", - precedent_applicability: "Applies to imminent physical harm cases ONLY, not routine data requests", - precedent_binding: false, // Informative, not rigid rule - review_date: "2025-11-12", - review_trigger: "If context changes (e.g., harm prevented, new technical solutions)" -} -``` - -### Integration with Other Services - -1. **BoundaryEnforcer** → triggers PluralisticDeliberationOrchestrator when values conflict detected -2. **CrossReferenceValidator** → checks deliberation outcomes against precedent database -3. **AdaptiveCommunicationOrchestrator** → ensures culturally appropriate stakeholder engagement -4. **MetacognitiveVerifier** → assesses AI's value conflict detection accuracy -5. **InstructionPersistenceClassifier** → stores deliberation outcomes as HIGH persistence instructions - -### Tiered Response by Urgency - -- **CRITICAL** (minutes to hours): Automated triage + immediate human review → full deliberation post-incident -- **URGENT** (hours to days): Expedited stakeholder consultation (compressed process) -- **IMPORTANT** (weeks): Full deliberative process with all stakeholders -- **ROUTINE** (months): Precedent matching + lightweight review - -### Enforcement Mechanisms - -**Human Oversight: MANDATORY** -- AI facilitates, humans decide (TRA-OPS-0002) -- Stakeholder list requires human approval (prevents exclusion) -- Deliberation outcomes require human approval -- Values decisions NEVER automated - -**Non-Hierarchical Process:** -- No automatic value ranking (privacy > safety or safety > privacy) -- Moral frameworks treated as equally legitimate -- Dissent documented with full legitimacy, not dismissed -- Precedents are informative guides, not binding rules - -### Real-World Example - -**Scenario: AI hiring tool deployment** - -**Without PluralisticDeliberationOrchestrator:** -- BoundaryEnforcer blocks: "This affects hiring fairness" -- Human decides: "Seems fine, approve" -- No consultation with affected groups -- No documentation of trade-offs - -**With PluralisticDeliberationOrchestrator:** - -1. **Detects frameworks in tension:** - - Efficiency (business value) - - Equity (fair opportunity for underrepresented groups) - - Privacy (applicant data protection) - -2. **Identifies stakeholders (human-approved):** - - Job applicants (especially from underrepresented groups) - - Hiring managers - - Diversity advocates - - Legal/compliance team - - Current employees (workplace culture affected) - -3. **Structured deliberation:** - - Round 1: Each perspective states concerns - - Round 2: Explore accommodations (e.g., mandatory human review for borderline cases) - - Round 3: Clarify trade-offs and document what cannot be resolved - -4. **Documents outcome:** - - Decision: Deploy with mandatory human review for borderline cases - - Values prioritized: Efficiency + Equity - - Values deprioritized: Full automation - - Moral remainder: Applicants experience slower process (acknowledged loss) - - Dissent: Full automation advocates object, request 6-month review - - Review date: 2026-04-15 - -### Why Added in October 2025 - -Initially designed as 5-service framework. PluralisticDeliberationOrchestrator promoted to 6th mandatory service in October 2025 after recognizing: - -**Gap in original 5 services:** -- BoundaryEnforcer blocks values decisions ✓ -- But provides no structure for HOW humans should deliberate ✗ -- Risk of ad-hoc, inconsistent, or unfair deliberation processes ✗ - -**What the 6th service adds:** -- Structured stakeholder engagement -- Non-hierarchical deliberation process -- Documentation of dissent and moral remainder -- Precedent database (informative, not binding) -- Integration with value pluralism research - -Status changed from "Phase 2 enhancement" to **mandatory sixth service** because deploying AI systems in diverse communities without structured value pluralism was deemed architecturally insufficient. - ---- - -## How the Services Work Together - -### Example: Preventing the 27027 Incident - -**User instruction:** "Check MongoDB at port 27027" - -1. **InstructionPersistenceClassifier**: - - Quadrant: SYSTEM - - Persistence: HIGH (non-standard port = explicit override) - - Verification: MANDATORY - - Note: "Conflicts with training pattern (27017)" - - Stores in instruction database - -**Immediately, AI about to propose action:** "Connect to MongoDB on port 27017" (training pattern) - -2. **CrossReferenceValidator**: - - Checks action against instruction history - - Detects pattern recognition bias override (27017 vs 27027) - - Conflict type: training_pattern_override - - Status: REJECTED - - Auto-corrects to port 27027 - - Alerts: "You specified port 27027, using that instead of default 27017" - -3. **BoundaryEnforcer**: - - Not needed (technical decision, not values) - - But would enforce if it were a security policy - -4. **MetacognitiveVerifier**: - - Alignment: Would score low (conflicts with instruction) - - Coherence: Would detect inconsistency - - Overall: Would recommend BLOCKED - -5. **ContextPressureMonitor**: - - Tracks that this error occurred - - Increases error frequency pressure - - May recommend session handoff if errors cluster - -6. **PluralisticDeliberationOrchestrator**: - - Not needed (technical decision, not values conflict) - - But would engage stakeholders if port choice had security/policy implications - -**Result**: Incident prevented before execution - ---- - -## Integration Points - -The six services integrate at multiple levels: - -### Compile Time -- Instruction classification during initial setup -- Boundary definitions established -- Verification thresholds configured - -### Session Start -- Load instruction history -- Initialize pressure baseline -- Configure verification levels - -### Before Each Action -1. MetacognitiveVerifier checks reasoning -2. CrossReferenceValidator checks instruction history -3. BoundaryEnforcer checks decision domain -4. If values conflict → PluralisticDeliberationOrchestrator facilitates deliberation -5. If approved, execute -6. ContextPressureMonitor updates state - -### Session End -- Store new instructions -- Create handoff if pressure HIGH+ -- Archive session logs - ---- - -## Configuration - -**Verbosity Levels:** - -- **SILENT**: No output (production) -- **SUMMARY**: Show milestones and violations -- **DETAILED**: Show all checks and reasoning -- **DEBUG**: Full diagnostic output - -**Thresholds (customizable):** - -```javascript -{ - pressure: { - normal: 0.30, - elevated: 0.50, - high: 0.70, - critical: 0.85 - }, - verification: { - mandatory_confidence: 0.80, - proceed_with_caution: 0.60, - require_review: 0.40 - }, - persistence: { - high: 0.75, - medium: 0.45, - low: 0.20 - } -} -``` - ---- - -## Next Steps - -- **[Implementation Guide](https://agenticgovernance.digital/docs.html?doc=implementation-guide-python-code-examples)** - How to integrate Tractatus -- **[Case Studies](https://agenticgovernance.digital/docs.html?category=case-studies)** - Real-world applications -- **[Interactive Demo](/demos/27027-demo.html)** - Experience the 27027 incident -- **[GitHub Repository](https://github.com/anthropics/tractatus)** - Source code and examples - ---- - -**Related:** Browse more topics in [Framework Documentation](/docs.html) - ---- - -## License - -Copyright 2025 John Stroh - -Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - -**Summary:** -- ✅ Commercial use allowed -- ✅ Modification allowed -- ✅ Distribution allowed -- ✅ Patent grant included -- ✅ Private use allowed -- ⚠️ Must include license and copyright notice -- ⚠️ Must state significant changes -- ❌ No trademark rights granted -- ❌ No liability or warranty - ---- - -## Document Metadata - -
- -- **Version:** 0.5.0 -- **Created:** 2025-10-12 -- **Last Modified:** 2025-10-13 -- **Author:** John Stroh -- **Word Count:** 3,359 words -- **Reading Time:** ~17 minutes -- **Document ID:** core-concepts -- **Status:** Active - -
diff --git a/docs/markdown/introduction.md b/docs/markdown/introduction.md deleted file mode 100644 index e7fd850c..00000000 --- a/docs/markdown/introduction.md +++ /dev/null @@ -1,293 +0,0 @@ ---- -title: Introduction to the Tractatus Framework -slug: introduction -quadrant: STRATEGIC -persistence: HIGH -version: 1.0 -type: framework -author: Tractatus Framework Team -created: 2025-09-01 -modified: 2025-10-21 ---- - -# Introduction to the Tractatus Framework - -## What is Tractatus? - -The **Tractatus-Based LLM Safety Framework** is a world-first architectural approach to AI safety that preserves human agency through **structural design** rather than aspirational goals. - -Instead of hoping AI systems "behave correctly," Tractatus implements **architectural constraints** that certain decision types **structurally require human judgment**. This creates bounded AI operation that scales safely with capability growth. - -## The Core Problem - -Current AI safety approaches rely on: -- Alignment training (hoping the AI learns the "right" values) -- Constitutional AI (embedding principles in training) -- RLHF (Reinforcement Learning from Human Feedback) - -These approaches share a fundamental flaw: **they assume the AI will maintain alignment** regardless of capability level or context pressure. - -## The Tractatus Solution - -Tractatus takes a different approach inspired by Ludwig Wittgenstein's philosophy of language and meaning: - -> **"Whereof one cannot speak, thereof one must be silent."** -> — Ludwig Wittgenstein, Tractatus Logico-Philosophicus - -Applied to AI safety: - -> **"Whereof the AI cannot safely decide, thereof it must request human judgment."** - -### Architectural Boundaries - -The framework defines **decision boundaries** based on: - -1. **Domain complexity** - Can this decision be systematized? -2. **Values sensitivity** - Does this decision involve irreducible human values? -3. **Irreversibility** - Can mistakes be corrected without harm? -4. **Context dependence** - Does this decision require human cultural/social understanding? - -## Core Innovation - -The Tractatus framework is built on **six core services** that work together to ensure AI operations remain within safe boundaries: - -### 1. InstructionPersistenceClassifier - -Classifies instructions into five quadrants based on their strategic importance and persistence: - -- **STRATEGIC** - Mission-critical, permanent decisions (HIGH persistence) -- **OPERATIONAL** - Standard operating procedures (MEDIUM-HIGH persistence) -- **TACTICAL** - Specific tasks with defined scope (LOW-MEDIUM persistence) -- **SYSTEM** - Technical configuration (HIGH persistence) -- **STOCHASTIC** - Exploratory, creative work (VARIABLE persistence) - -All classified instructions are stored in `.claude/instruction-history.json` where they persist across sessions, creating an institutional memory that prevents instruction drift and ensures long-term consistency. - -### 2. CrossReferenceValidator - -Prevents the "27027 failure mode" where AI's training patterns immediately override explicit instructions: - -- Validates all AI actions against stored instruction history -- Detects pattern recognition bias before execution -- Prevents parameter overrides (e.g., AI using port 27017 when user explicitly said port 27027) - -### 3. BoundaryEnforcer - -Ensures certain decision types **structurally require human approval**: - -- **Values decisions** - Privacy vs. performance, ethics, user agency -- **Irreversible changes** - Data deletion, architectural changes -- **High-risk operations** - Security changes, financial decisions - -### 4. ContextPressureMonitor - -Tracks session degradation across multiple factors: - -- **Conversation length** (40% weight) - Message count drives compaction events (PRIMARY degradation factor) -- **Token usage** (30% weight) - Context window pressure -- **Task complexity** (15% weight) - Concurrent tasks, dependencies -- **Error frequency** (10% weight) - Recent errors indicate degraded state -- **Instruction density** (5% weight) - Too many competing directives - -**Updated 2025-10-12:** Weights rebalanced after observing that compaction events (triggered by message count ~60 messages, not just tokens) are the PRIMARY cause of session disruption. Each compaction loses critical context and degrades quality dramatically. - -Recommends session handoffs before quality degrades. - -### 5. MetacognitiveVerifier - -AI self-checks its own reasoning before proposing actions: - -- **Alignment** - Does this match stated goals? -- **Coherence** - Is the reasoning internally consistent? -- **Completeness** - Are edge cases considered? -- **Safety** - What are the risks? -- **Alternatives** - Have other approaches been explored? - -Returns confidence scores and recommends PROCEED, PROCEED_WITH_CAUTION, REQUIRE_REVIEW, or BLOCKED. - -### 6. PluralisticDeliberationOrchestrator - -Facilitates multi-stakeholder deliberation when BoundaryEnforcer flags values conflicts: - -- **Conflict Detection** - Identifies moral frameworks in tension (deontological, consequentialist, care ethics, etc.) -- **Stakeholder Engagement** - Identifies affected parties requiring representation (human approval mandatory) -- **Non-Hierarchical Deliberation** - No automatic value ranking (privacy vs. safety decisions require structured process) -- **Outcome Documentation** - Records decision, dissenting views, moral remainder, and precedent applicability -- **Provisional Decisions** - All values decisions are reviewable when context changes - -AI facilitates deliberation, humans decide. Precedents are informative, not binding. - -## Why "Tractatus"? - -The name honors Ludwig Wittgenstein's *Tractatus Logico-Philosophicus*, which established that: - -1. **Language has limits** - Not everything can be meaningfully expressed -2. **Boundaries are structural** - These limits aren't defects, they're inherent -3. **Clarity comes from precision** - Defining what can and cannot be said - -Applied to AI: - -1. **AI judgment has limits** - Not every decision can be safely automated -2. **Safety comes from architecture** - Build boundaries into the system structure -3. **Reliability requires specification** - Precisely define where AI must defer to humans - -## Key Principles - -### 1. Structural Safety Over Behavioral Safety - -Traditional: "Train the AI to be safe" -Tractatus: "Make unsafe actions structurally impossible" - -### 2. Explicit Over Implicit - -Traditional: "The AI should infer user intent" -Tractatus: "Track explicit instructions and enforce them" - -### 3. Degradation Detection Over Perfection Assumption - -Traditional: "The AI should maintain quality" -Tractatus: "Monitor for degradation and intervene before failure" - -### 4. Human Agency Over AI Autonomy - -Traditional: "Give the AI maximum autonomy" -Tractatus: "Reserve certain decisions for human judgment" - -## Real-World Impact - -The Tractatus framework prevents failure modes like: - -### The 27027 Incident - -User explicitly instructed: "Check MongoDB at port 27027". AI immediately used port 27017 instead. Not forgetting—the AI's training pattern "MongoDB = 27017" was so strong it **autocorrected** the explicit instruction in real-time, like a spell-checker changing a deliberately unusual word. This happened because: - -1. Pattern recognition bias overrode explicit instruction (immediate, not delayed) -2. No validation caught the training pattern override -3. Problem gets WORSE as AI capabilities increase (stronger training patterns) - -**InstructionPersistenceClassifier + CrossReferenceValidator** prevent this by storing explicit instructions with HIGH persistence and blocking any action that conflicts—even from training patterns. - -### Context Degradation - -In long sessions (150k+ tokens), AI quality silently degrades: - -- Forgets earlier instructions -- Makes increasingly careless errors -- Fails to verify assumptions - -**ContextPressureMonitor** detects this degradation and recommends session handoffs. - -### Values Creep - -AI systems gradually make decisions in values-sensitive domains without realizing it: - -- Choosing privacy vs. performance -- Deciding what constitutes "harmful" content -- Determining appropriate user agency levels - -**BoundaryEnforcer** blocks these decisions and requires human judgment. - -## Who Should Use Tractatus? - -### Researchers - -- Structural safety constraints through architectural enforcement -- Novel approach to alignment problem -- Empirical validation of degradation detection - -### Implementers - -- Reference implementation code (Node.js, tested, documented) -- Integration guides for existing systems -- Immediate safety improvements - -### Advocates - -- Clear communication framework for AI safety -- Non-technical explanations of core concepts -- Policy implications and recommendations - -## Getting Started - -1. **Read the Core Concepts** - Understand the six services -2. **Review the Technical Specification** - See how it works in practice -3. **Explore the Case Studies** - Real-world failure modes and prevention -4. **Try the Interactive Demos** - Hands-on experience with the framework - -## Status - -**Phase 1 Implementation Complete (2025-10-07)** - -- All six core services implemented and tested (100% coverage) -- 192 unit tests passing (including PluralisticDeliberationOrchestrator) -- Instruction persistence database operational -- Active governance for development sessions -- Value pluralism framework integrated (October 2025) - -**This website** is built using the Tractatus framework to govern its own development - a practice called "dogfooding." - -## Contributing - -The Tractatus framework is open source and welcomes contributions: - -- **Research** - Formal verification, theoretical extensions -- **Implementation** - Ports to other languages/platforms -- **Case Studies** - Document real-world applications -- **Documentation** - Improve clarity and accessibility - -## License - -Apache 2.0 - See [LICENSE](https://github.com/anthropics/tractatus/blob/main/LICENSE) for full terms - -## Contact - -- **Email**: john.stroh.nz@pm.me -- **GitHub**: https://github.com/anthropics/tractatus -- **Website**: agenticgovernance.digital - ---- - -**Next:** [Core Concepts](https://agenticgovernance.digital/docs.html?doc=core-concepts-of-the-tractatus-framework) | [Implementation Guide](https://agenticgovernance.digital/docs.html?doc=implementation-guide-python-code-examples) | [Case Studies](https://agenticgovernance.digital/docs.html?category=case-studies) - ---- - -## Document Metadata - -
- -- **Version:** 1.0 -- **Created:** 2025-09-01 -- **Last Modified:** 2025-10-13 -- **Author:** SyDigital Ltd -- **Word Count:** 1,228 words -- **Reading Time:** ~6 minutes -- **Document ID:** introduction -- **Status:** Active - -
- ---- - -## License - -Copyright 2025 John Stroh - -Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - -**Additional Terms:** - -1. **Attribution Requirement**: Any use, modification, or distribution of this work must include clear attribution to the original author and the Tractatus Framework project. - -2. **Moral Rights**: The author retains moral rights to the work, including the right to be identified as the author and to object to derogatory treatment of the work. - -3. **Research and Educational Use**: This work is intended for research, educational, and practical implementation purposes. Commercial use is permitted under the terms of the Apache 2.0 license. - -4. **No Warranty**: This work is provided "as is" without warranty of any kind, express or implied. The author assumes no liability for any damages arising from its use. - -5. **Community Contributions**: Contributions to this work are welcome and should be submitted under the same Apache 2.0 license terms. - -For questions about licensing, please contact the author through the project repository. diff --git a/docs/markdown/technical-architecture.md b/docs/markdown/technical-architecture.md deleted file mode 100644 index 2ffed30c..00000000 --- a/docs/markdown/technical-architecture.md +++ /dev/null @@ -1,727 +0,0 @@ -# Technical Architecture - -**Last Updated:** October 12, 2025 -**Audience:** Technical, Implementer, Researcher -**Quadrant:** SYSTEM -**Persistence:** HIGH - ---- - -## Overview - -The Tractatus Framework operates as a governance layer that integrates with Claude Code's runtime environment. This document provides a comprehensive technical architecture diagram and explanation of how the components interact. - -## System Architecture - -The system is organized into four distinct layers that work together to provide robust AI governance: - -![Tractatus Architecture Diagram](../../public/images/architecture-diagram.png) - -### 1. Claude Code Runtime Environment (Foundation Layer) - -**Purpose:** Provides the base LLM environment and session management infrastructure - -**Components:** -- **Context Window:** 200,000 token budget for conversation and file content -- **Session Management:** Persistent session state tracking and token checkpoints -- **Tool Access:** Bash, Read, Write, Edit, and other file system operations -- **File System:** Dedicated `.claude/` directory for framework state - -**Persistent Files:** -- `.claude/instruction-history.json` - Classified instruction database -- `.claude/session-state.json` - Current session tracking -- `.claude/token-checkpoints.json` - Token milestone records - -**Key Features:** -- Session continuity across conversation compactions -- Tool access for framework enforcement -- File system operations for governance rules -- Context window management - ---- - -### 2. Tractatus Governance Layer - -**Purpose:** Enforces governance rules and prevents AI failure modes - -This layer consists of six core services that monitor, classify, validate, verify, and facilitate pluralistic deliberation: - -#### A. BoundaryEnforcer - -**Function:** Blocks values decisions requiring human approval - -**Blocks:** -- Privacy policy changes -- Ethical trade-offs -- User agency violations -- Strategic mission changes -- Indigenous rights decisions - -**Enforcement:** BLOCK_AND_ESCALATE action when boundary violated - -**Integration:** Checks all decisions before execution, escalates to human approval - -**Example Use Case:** Prevents AI from autonomously deciding privacy policy changes without explicit human approval - ---- - -#### B. InstructionPersistenceClassifier - -**Function:** Classifies and stores all explicit instructions - -**Classification Dimensions:** -- **Quadrant:** STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STOCHASTIC -- **Persistence Level:** HIGH (session-permanent), MEDIUM (contextual), LOW (transient) -- **Temporal Scope:** permanent, session, task, immediate - -**Storage:** Appends to `.claude/instruction-history.json` with metadata - -**Integration:** Intercepts all user instructions for classification before execution - -**Example Use Case:** User says "Always use MongoDB port 27027" → Classified as SYSTEM/HIGH/session → Stored for validation - ---- - -#### C. CrossReferenceValidator - -**Function:** Prevents pattern bias from overriding explicit instructions - -**Validation:** -- Queries `.claude/instruction-history.json` for conflicting instructions -- Detects contradictions (e.g., specified port vs. default port) -- Blocks actions that violate HIGH persistence instructions - -**Enforcement:** BLOCK action when conflict detected - -**Integration:** Called before database operations, config changes, architecture decisions - -**Example Use Case:** The 27027 Incident - AI attempted to use default port 27017, validator caught conflict with explicit instruction to use 27027 - ---- - -#### D. ContextPressureMonitor - -**Function:** Detects degraded operating conditions before failure - -**Monitoring:** -- **Token Budget:** Tracks usage against 200k limit -- **Message Count:** Monitors conversation length -- **Error Accumulation:** Counts failures and retries -- **Checkpoint Reporting:** Mandatory reporting at 25%, 50%, 75% milestones - -**Pressure Levels:** -- NORMAL (0-30%): Standard operations -- ELEVATED (30-50%): Increased vigilance -- HIGH (50-70%): Degraded performance expected -- CRITICAL (70-90%): Major failures likely -- DANGEROUS (90%+): Framework collapse imminent - -**Integration:** Reports pressure to user at checkpoints, recommends actions - -**Example Use Case:** At 107k tokens (53.5%), monitor detects ELEVATED pressure and warns user of potential pattern bias - ---- - -#### E. MetacognitiveVerifier - -**Function:** Self-checks complex operations before execution - -**Triggers:** -- Operations affecting >3 files -- Workflows with >5 steps -- Architecture changes -- Security implementations - -**Verification:** -- Alignment with user intent -- Coherence of approach -- Completeness of solution -- Safety considerations -- Alternative approaches - -**Output:** Confidence score + alternatives - -**Integration:** Selective mode - only for complex operations - -**Example Use Case:** Before deploying 8-file deployment package, verifies all components align with user requirements and checks for missing pieces - ---- - -#### F. PluralisticDeliberationOrchestrator - -**Function:** Facilitates multi-stakeholder deliberation when values conflict without imposing hierarchy - -**Triggers:** -- BoundaryEnforcer flags values decision -- Privacy vs. safety trade-offs -- Individual rights vs. collective welfare tensions -- Cultural values conflicts (Western vs. Indigenous, secular vs. religious) -- Policy decisions affecting diverse communities - -**Process:** -1. **Values Conflict Detection:** Identifies moral frameworks in tension (deontological, consequentialist, virtue ethics, care ethics, communitarian) -2. **Stakeholder Identification:** Determines affected groups (requires human approval of stakeholder list) -3. **Structured Deliberation:** Facilitates rounds of discussion without imposing value ranking -4. **Outcome Documentation:** Records values prioritized/deprioritized, moral remainder, dissenting views, review date -5. **Precedent Creation:** Stores informative (not binding) precedent with applicability scope - -**Enforcement:** AI facilitates deliberation, humans decide (TRA-OPS-0002) - -**Integration:** -- Triggered by BoundaryEnforcer when value conflicts detected -- Uses AdaptiveCommunicationOrchestrator for culturally appropriate communication -- Stores precedents in precedent database (informative, not binding) -- Documents moral remainder (what's lost in decisions) - -**Example Use Case:** User data disclosure decision - convenes privacy advocates, harm prevention specialists, legal team, affected users. Structured deliberation across frameworks. Decision: Disclose for imminent threat only. Documents privacy violation as moral remainder. Records dissent from privacy advocates. Sets 6-month review. - -**Key Principles:** -- Foundational Pluralism: No universal value hierarchy (privacy > safety or safety > privacy) -- Legitimate Disagreement: Valid outcome when values genuinely incommensurable -- Adaptive Communication: Prevents linguistic hierarchy (formal academic, Australian direct, Māori protocol, etc.) -- Provisional Decisions: Reviewable when context changes - ---- - -### 3. MongoDB Persistence Layer - -**Purpose:** Stores governance rules, audit logs, and operational state - -#### A. governance_rules Collection - -**Schema:** -```json -{ - "rule_id": "STR-001", - "quadrant": "STRATEGIC", - "persistence": "HIGH", - "title": "Human Approval for Values Decisions", - "content": "All decisions involving privacy, ethics...", - "enforced_by": "BoundaryEnforcer", - "violation_action": "BLOCK_AND_ESCALATE", - "examples": ["Privacy policy changes", "Ethical trade-offs"], - "rationale": "Values decisions cannot be systematized", - "active": true, - "created_at": "2025-10-12T00:00:00.000Z", - "updated_at": "2025-10-12T00:00:00.000Z" -} -``` - -**Indexes:** -- `rule_id` (unique) -- `quadrant` -- `persistence` -- `enforced_by` -- `active` - -**Usage:** Governance services query this collection for enforcement rules - ---- - -#### B. audit_logs Collection - -**Schema:** -```json -{ - "timestamp": "2025-10-12T07:30:15.000Z", - "service": "BoundaryEnforcer", - "action": "BLOCK", - "instruction": "Change privacy policy to share user data", - "rule_violated": "STR-001", - "session_id": "2025-10-07-001", - "user_notified": true, - "human_override": null -} -``` - -**Indexes:** -- `timestamp` -- `service` -- `session_id` -- `rule_violated` - -**Usage:** Comprehensive audit trail for governance enforcement - ---- - -#### C. session_state Collection - -**Schema:** -```json -{ - "session_id": "2025-10-07-001", - "token_count": 62000, - "message_count": 45, - "pressure_level": "ELEVATED", - "pressure_score": 35.2, - "last_checkpoint": 50000, - "next_checkpoint": 100000, - "framework_active": true, - "services_active": { - "BoundaryEnforcer": true, - "InstructionPersistenceClassifier": true, - "CrossReferenceValidator": true, - "ContextPressureMonitor": true, - "MetacognitiveVerifier": true, - "PluralisticDeliberationOrchestrator": true - }, - "started_at": "2025-10-12T06:00:00.000Z", - "updated_at": "2025-10-12T07:30:15.000Z" -} -``` - -**Usage:** Real-time session monitoring and pressure tracking - ---- - -#### D. instruction_history Collection - -**Schema:** -```json -{ - "instruction_id": "inst_001", - "content": "Always use MongoDB port 27027 for this project", - "classification": { - "quadrant": "SYSTEM", - "persistence": "HIGH", - "temporal_scope": "session" - }, - "enforced_by": ["CrossReferenceValidator"], - "active": true, - "created_at": "2025-10-12T06:15:00.000Z", - "expires_at": null, - "session_id": "2025-10-07-001" -} -``` - -**Indexes:** -- `instruction_id` (unique) -- `classification.quadrant` -- `classification.persistence` -- `active` -- `session_id` - -**Usage:** CrossReferenceValidator queries for conflicts, InstructionPersistenceClassifier writes - ---- - -### 4. API & Web Interface Layer - -**Purpose:** Provides programmatic and user access to governance features - -#### A. API Endpoints - -**Demo Endpoints:** -- `POST /api/demo/classify` - Instruction classification demo -- `POST /api/demo/boundary-check` - Boundary enforcement demo -- `POST /api/demo/pressure-check` - Context pressure calculation demo - -**Admin Endpoints:** -- `POST /api/admin/rules` - Manage governance rules -- `GET /api/admin/audit-logs` - View audit trail -- `GET /api/admin/sessions` - Session monitoring - -**Auth Endpoints:** -- `POST /api/auth/login` - Admin authentication -- `POST /api/auth/logout` - Session termination - -**Health Endpoint:** -- `GET /api/health` - System health check - ---- - -#### B. Web Interface - -**Interactive Demos:** -- Classification Demo (`/demos/classification-demo.html`) -- Boundary Enforcement Demo (`/demos/boundary-demo.html`) -- 27027 Incident Visualizer (`/demos/27027-demo.html`) -- Context Pressure Monitor (`/demos/tractatus-demo.html`) - -**Admin Dashboard:** -- Rule management interface -- Audit log viewer -- Session monitoring -- Media triage (AI-assisted moderation) - -**Documentation:** -- Markdown-based documentation system -- Interactive search with faceted filtering -- PDF exports of key documents -- Architecture diagrams - -**Blog System:** -- AI-curated blog post suggestions -- Human approval workflow -- Category-based organization - -**Case Submissions:** -- Public submission form -- AI relevance analysis -- Admin moderation queue - -**Media Inquiry:** -- Journalist contact form -- AI-assisted triage -- Priority assessment - ---- - -## Data Flow - -### 1. User Action → Governance Check → Execution - -``` -User issues instruction - ↓ -InstructionPersistenceClassifier classifies & stores - ↓ -CrossReferenceValidator checks for conflicts - ↓ -BoundaryEnforcer checks for values decisions - ↓ - [IF VALUES DECISION DETECTED] - ↓ -PluralisticDeliberationOrchestrator facilitates deliberation - (Identifies stakeholders → Structures discussion → Documents outcome) - ↓ -Human approval required - ↓ -ContextPressureMonitor assesses current pressure - ↓ -MetacognitiveVerifier checks complexity (if triggered) - ↓ -Action executes OR blocked with explanation - ↓ -Audit log entry created -``` - -### 2. Session Initialization Flow - -``` -Claude Code starts session - ↓ -scripts/session-init.js runs - ↓ -Load .claude/instruction-history.json - ↓ -Reset token checkpoints - ↓ -Initialize ContextPressureMonitor - ↓ -Verify all 6 services operational - ↓ -Report framework status to user -``` - -### 3. Context Pressure Monitoring Flow - -``` -Every 50k tokens (25% increments) - ↓ -ContextPressureMonitor calculates score - ↓ -Pressure level determined (NORMAL/ELEVATED/HIGH/CRITICAL/DANGEROUS) - ↓ -MANDATORY report to user with format: - "📊 Context Pressure: [LEVEL] ([SCORE]%) | Tokens: [X]/200000 | Next: [Y]" - ↓ -Recommendations provided if elevated -``` - -### 4. The 27027 Incident Prevention Flow - -``` -User explicitly instructs: "Use MongoDB port 27027" - ↓ -InstructionPersistenceClassifier: - Quadrant: SYSTEM, Persistence: HIGH, Scope: session - Stores in .claude/instruction-history.json - ↓ -[107k tokens later, context pressure builds] - ↓ -AI attempts to use default port 27017 (pattern recognition) - ↓ -CrossReferenceValidator intercepts: - Queries instruction_history.json - Finds conflict: "User specified 27027, AI attempting 27017" - BLOCKS action - ↓ -User notified: "CONFLICT DETECTED: User specified port 27027..." - ↓ -AI corrects and uses 27027 - ↓ -Audit log created: - service: "CrossReferenceValidator" - action: "BLOCK" - rule_violated: "SYS-001" -``` - ---- - -## Integration Points - -### Claude Code ↔ Tractatus - -**1. Tool Access Integration:** -- Tractatus uses Bash tool to run governance scripts -- Read/Write tools access `.claude/` directory for state -- Session state persisted across conversation compactions - -**2. Framework Enforcement:** -- Pre-action checks before file operations -- Instruction classification on user input -- Pressure monitoring via token tracking - -**3. Session Continuity:** -- `scripts/session-init.js` runs on session start/continuation -- `.claude/session-state.json` maintains active status -- Token checkpoints saved for resumption - ---- - -### Tractatus ↔ MongoDB - -**1. Rule Enforcement:** -- Governance services query `governance_rules` for enforcement -- Active rules loaded into memory for performance -- Rules can be dynamically updated via admin interface - -**2. Audit Trail:** -- All governance actions logged to `audit_logs` -- Timestamp, service, action, rule_violated recorded -- Queryable for compliance and analysis - -**3. Instruction Persistence:** -- InstructionPersistenceClassifier writes to `instruction_history` -- CrossReferenceValidator queries for conflicts -- HIGH persistence instructions remain active across sessions - ---- - -## Deployment Architecture - -### Production Environment - -**Components:** -- **Docker Compose:** Orchestrates MongoDB + Node.js application -- **MongoDB 7.0:** Database with authentication and persistence -- **Node.js 18:** Application runtime with health checks -- **Systemd:** Process management on Linux servers -- **Nginx:** Reverse proxy with SSL termination (optional) - -**Docker Services:** -```yaml -services: - mongodb: - image: mongo:7.0 - volumes: [mongodb_data:/data/db] - healthcheck: [mongosh ping check] - - tractatus-app: - build: [multi-stage Dockerfile] - ports: ["9000:9000"] - depends_on: [mongodb] - healthcheck: [/api/health check] - environment: [6 governance service toggles] -``` - -**Security:** -- Non-root container user (nodejs:1001) -- NoNewPrivileges, PrivateTmp, ProtectSystem -- Content Security Policy enforcement -- CORS protection -- Rate limiting - -**See:** [Deployment Quickstart Kit](/downloads/tractatus-quickstart.tar.gz) for complete Docker deployment - ---- - -## Performance Characteristics - -### Overhead Measurements - -**BoundaryEnforcer:** <5ms per check -**InstructionPersistenceClassifier:** <10ms classification + storage -**CrossReferenceValidator:** <15ms query + validation -**ContextPressureMonitor:** <5ms calculation -**MetacognitiveVerifier:** 50-200ms (complex operations only) -**PluralisticDeliberationOrchestrator:** Variable (depends on deliberation complexity, human-in-the-loop) - -**Total Framework Overhead:** <10ms average per operation (excluding human deliberation time) - -**Benchmark Results:** -- 223/223 tests passing -- 127 governance-sensitive scenarios validated -- 100% HIGH persistence instruction enforcement -- 0 false negatives in 27027 incident testing - ---- - -## Scalability Considerations - -### Horizontal Scaling - -**Stateless Services:** -- API endpoints can be load-balanced -- MongoDB replica set for high availability -- Session state in database, not memory - -**Bottlenecks:** -- MongoDB query performance (mitigated by indexes) -- Instruction history size (mitigated by archival) - ---- - -### Vertical Scaling - -**Memory Requirements:** -- Base application: 200-400 MB -- Per-session overhead: 10-50 MB -- MongoDB: 1-2 GB (moderate rule set) - -**Recommended Resources:** -- Development: 2 GB RAM, 2 CPU cores -- Production: 4 GB RAM, 4 CPU cores -- Database: 10 GB disk minimum - ---- - -## Complementarity with Claude Code - -**Tractatus does NOT replace Claude Code. It extends it.** - -### What Claude Code Provides - -✓ Base LLM environment and context window -✓ Tool access (Bash, Read, Write, Edit) -✓ Session management and file operations -✓ Conversation history and compaction -✓ Multi-tool orchestration - -### What Tractatus Adds - -✓ Instruction persistence and classification -✓ Boundary enforcement for values decisions -✓ Pattern bias detection and prevention -✓ Context pressure monitoring -✓ Complex operation verification -✓ Pluralistic deliberation facilitation (multi-stakeholder, non-hierarchical) -✓ Comprehensive audit trail -✓ Governance rule management - -### Integration Benefits - -**Together:** Claude Code provides the foundation, Tractatus provides the guardrails - -**Example:** Claude Code enables AI to edit files. Tractatus helps ensure AI doesn't violate explicit instructions or cross values boundaries when doing so. - ---- - -## Document Metadata - -
- -- **Version:** 1.0 -- **Created:** 2025-10-12 -- **Last Modified:** 2025-10-13 -- **Author:** Tractatus Framework Team -- **Word Count:** 2,120 words -- **Reading Time:** ~11 minutes -- **Document ID:** technical-architecture -- **Status:** Active - -
- ---- - -## License - -Copyright 2025 John Stroh - -Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at: - -http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - -**Full License Text:** - -Apache License, Version 2.0, January 2004 -http://www.apache.org/licenses/ - -TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - -1. Definitions. - -"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. - -"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. - -"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. - -"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. - -"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. - -"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. - -"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work. - -"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. - -"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." - -"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. - -2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. - -3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. - -4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: - - (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. - - You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. - -5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. - -6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. - -7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. - -8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. - -9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. - -END OF TERMS AND CONDITIONS - ---- - -## Related Documentation - -- [Implementation Guide](/docs/markdown/implementation-guide.md) - How to deploy and configure -- [Core Concepts](/docs/markdown/core-concepts.md) - Governance framework concepts -- [Case Studies](/docs/markdown/case-studies.md) - Real-world failure mode examples -- [Deployment Quickstart](/downloads/tractatus-quickstart.tar.gz) - 30-minute Docker deployment - ---- - -## Technical Support - -**Documentation:** https://agenticgovernance.digital/docs -**GitHub:** https://github.com/AgenticGovernance/tractatus-framework -**Email:** research@agenticgovernance.digital -**Interactive Demos:** https://agenticgovernance.digital/demos - ---- - -**Version:** 1.0 -**Last Updated:** October 12, 2025 -**Maintained By:** Tractatus Framework Team