Decision Versioning and Deprecation: A Complete Guide

When you run hopsule decision list from your terminal, you are looking at the current state of your organization’s judgment. But a list is static. In a high-velocity engineering team, decisions are anything but static. They evolve, they clash with new realities, and eventually, they must be retired to make room for better approaches. The challenge for most teams is that this evolution usually happens in Slack threads or buried in pull request comments, leaving the "official" record to rot. This is how technical debt begins—not with bad code, but with forgotten decisions.

In Hopsule, we treat decisions as first-class, versioned entities. We built this system because we saw too many teams struggle with "zombie decisions"—rules that everyone follows because "that’s how we’ve always done it," even though the original reasoning is no longer valid. As the CTO of Hopsule, I want to walk you through the mechanics of how we handle the lifecycle of a decision, from its first draft to its eventual deprecation, and how our tooling ensures that your team always has the right context at the right time.

The Architecture of an Enforceable Decision

Before we dive into versioning, we must understand what a decision actually is within the Hopsule ecosystem. Unlike a document in a general-purpose tool, a decision in Hopsule is a structured commitment. It is an enforceable constraint that carries with it a payload of memories. When you create a decision, you aren't just writing text; you are defining a rule that the Hopsule for VS Code extension will later use to warn developers when their code contradicts the team's agreed-upon direction.

Every decision has a lifecycle that moves through specific states. Understanding these states is critical for maintaining governance without stifling innovation. The states are:

• Draft: The decision is being formulated. It is visible to the team but not yet enforced. This is where Hopper, our AI assistant, helps you refine the language and detect potential conflicts with existing decisions.

• Pending: The decision is ready for review. It awaits formal acceptance by the designated authorities within the organization.

• Accepted: The decision is active. It is now an enforceable constraint. It appears in the Hopsule for VS Code sidebar and triggers warnings in the IDE.

• Deprecated: The decision is no longer active. It remains in the system for historical context but no longer triggers enforcement warnings.

This lifecycle ensures that enforcement is an act of remembrance, not a mechanism of control. By the time a decision reaches the "Accepted" state, it has been vetted, contextualized, and linked to the memories that explain its existence.

The Role of Memories in Decision Evolution

In Hopsule, memories are the "why" behind the "what." While a decision might change, the memories associated with it are append-only and immutable. This is a core philosophy of our system: organizations forget because they overwrite their history. Hopsule prevents this by ensuring that every version of a decision is backed by a persistent trail of reasoning. When you update a decision, you aren't deleting the old reasoning; you are adding a new memory that explains why the change was necessary.

Versioning: Managing the Evolution of Judgment

Software changes, and the decisions governing that software must change with it. However, simply editing a decision text is dangerous. If you change a rule without versioning it, you lose the ability to understand why code written six months ago looks the way it does. Hopsule handles this through explicit versioning. Every time an "Accepted" decision is modified, the system generates a new version and requires a justification for the change.

When you use the Hopsule Dashboard or the Hopsule CLI to update a decision, the previous version is archived but remains accessible. This creates a lineage of judgment. If a developer encounters a block of code that seems to violate a current decision, they can look at the version history to see if that code was compliant with the decision as it existed when the code was written. This traceability is what transforms a simple tool into a true memory system.

Consider a scenario where your team decides to move from a monolithic event bus to a distributed message queue. This isn't a change that happens overnight. You might have an existing decision titled "Event Handling Strategy" that mandates the use of the internal bus. To update this, you would create a new version of the decision. The Hopsule CLI command would look like this:

This creates a new version in a "Pending" state, allowing the team to discuss the transition while the old "Accepted" version continues to provide enforcement for existing workflows. Once the new version is accepted, it replaces the old one as the active constraint, but the old version remains in the "Brain" (our Knowledge Graph) as a historical node.

The CLI Workflow: Hands-on Decision Management

For the engineers on my team, the terminal is the primary interface for interacting with Hopsule. The Hopsule CLI is designed to fit into the standard developer workflow, making decision management as seamless as a git commit. We believe that if decision-making feels like "documentation work," it won't happen. It must feel like engineering work.

To start a new decision-making process, a developer might run:

This command initializes a Draft decision. From here, the developer can use hopsule memory add to attach specific benchmarks, meeting notes, or architectural diagrams that support the proposal. The CLI provides an interactive TUI (Terminal User Interface) that allows you to browse the current Knowledge Graph and see how this new proposal might interact with existing architectural constraints.

Automating Governance with the Hopsule API

While the CLI is perfect for manual intervention, the Hopsule API allows for programmatic governance. Many of our enterprise users integrate Hopsule into their CI/CD pipelines. For example, a pre-commit hook can call the Hopsule API to check if the current changes violate any "Accepted" decisions. If a violation is found, the pipeline can surface the relevant decision and its associated memories directly in the build logs, providing the developer with immediate context on how to fix the issue.

The API also enables custom reporting. Engineering leaders can query the API to see the "velocity of decision-making"—how many decisions are moving from Draft to Accepted, and how many are being deprecated. This provides a high-level view of architectural health without requiring manual status updates.

Deprecation: The Art of Letting Go

Deprecation is perhaps the most overlooked aspect of engineering governance. Most systems only focus on the "now," leading to a cluttered environment where old rules conflict with new ones. In Hopsule, deprecation is a first-class operation. When a decision is deprecated, it is not deleted. Instead, its status is updated to "Deprecated," and it is moved to the historical section of the Knowledge Graph.

Why do we keep deprecated decisions? Because they are essential for understanding the "archaeology" of a codebase. When a new engineer joins the team and asks, "Why did we use this obscure library for data processing?" they can search Hopsule and find a deprecated decision that explains the constraints of five years ago. This prevents the "Chesterton's Fence" problem, where developers tear down existing structures without understanding why they were built in the first place.

To deprecate a decision via the CLI, the command is straightforward:

This action triggers several downstream effects:

• The decision is removed from the active enforcement list in Hopsule for VS Code.

• Hopper is notified that this decision is no longer an active constraint, preventing it from suggesting the old pattern in future drafts.

• The decision’s node in the Knowledge Graph turns gray, indicating its historical status, but its links to other decisions and memories remain intact.

Enforcement and Remembrance in the IDE

The true power of Hopsule’s versioning and deprecation system is realized in Hopsule for VS Code. This is where the "enforcement is remembrance" philosophy comes to life. As a developer writes code, the extension monitors the context. If the developer begins implementing a pattern that contradicts an "Accepted" decision, a subtle warning appears.

This isn't a linter that yells about semicolons. It's a context-aware system that says, "Wait, the team agreed three months ago to stop using this specific pattern because of security concerns. Here is the decision and the reasoning behind it." The developer can then click through to the Hopsule Dashboard to read the full history and the associated memories.

Handling Intentional Overrides

We recognize that there are always exceptions. Hopsule is not a rigid policy engine; it is a memory system. If a developer needs to violate a decision for a valid reason, Hopsule for VS Code allows for an "Intentional Override." When an override is performed, the developer is prompted to provide a reason. This reason is then automatically added as a new Memory to the decision, providing real-world feedback to the team that the decision might need to be versioned or deprecated.

This feedback loop is vital. If a decision is being overridden frequently, it’s a signal that the decision no longer fits the reality of the work. The Knowledge Graph will visualize these overrides as "stress points," alerting engineering leadership that a particular architectural choice is causing friction.

Context Packs and the Portability of Decision History

Decisions and memories don't just live within a single project. In large organizations, decisions often span multiple repositories or teams. This is where Context Packs (or Capsules) come into play. A Context Pack is a portable bundle of decisions and their associated memories that can be shared across different projects or even external AI sessions.

When you version a decision that is part of a Context Pack, you can choose how that change propagates. Context Packs themselves have a lifecycle:

This portability is especially powerful when using Hopsule MCP. By connecting an AI agent (like Claude or a custom agent) to a Context Pack via the Hopsule MCP server, you give that agent instant access to your team's decision history. The agent becomes context-aware automatically. It won't suggest a deprecated pattern because it "remembers" the decision to move away from it. Importantly, the MCP connection is read-only; AI can consume your decisions to provide better assistance, but it can never mutate your organization's judgment.

Visualizing the Brain: The Knowledge Graph

As decisions evolve and versions accumulate, the relationships between them become complex. The Hopsule Dashboard features the Knowledge Graph, also known as the "Brain," which provides a visual representation of your organization's memory. Each node in the graph is a decision, and the edges represent relationships—dependencies, conflicts, or successions.

When you version a decision, the Brain shows the transition. You can see how a single foundational decision in the early days of a project has branched into several more specific decisions as the system scaled. This visualization is invaluable during architectural reviews or when onboarding senior leadership. Instead of wading through hundreds of documents, they can see the map of the team's judgment and how it has evolved over time.

The Brain also highlights "orphaned" decisions—those that are accepted but have no linked memories or related decisions. These are often signs of "drive-by" decision-making that lacks sufficient context, prompting the team to add the necessary memories before the reasoning is lost to time.

Conclusion: Building a Resilient Memory Layer

Version control changed how we manage code. Hopsule is changing how we manage the judgment that produces that code. By treating decisions as versioned, enforceable, and portable entities, we enable engineering organizations to grow without losing their way. We move away from the "culture of forgetting" and toward a culture of intentional remembrance.

As we look forward, we are expanding the capabilities of Hopper to provide even more proactive insights. Imagine an AI assistant that doesn't just help you draft a decision, but predicts the downstream impact of a deprecation based on your Knowledge Graph. We are building a future where the collective memory of an engineering team is its greatest asset, preserved and enforced through every line of code written.

If you haven't already, I encourage you to install the Hopsule CLI and run hopsule init in your primary project. Start by capturing just one decision that the team made this week. Attach the reasoning as a memory. See how it feels to have that decision surface in your IDE the next day. This is the first step toward building an organization that remembers.