Recover QueueGuard from False Consensus

Use Claude Code and Git history to recover QueueGuard from false consensus.

Introduction

30 Second Summary

When you inherit someone else's software, several files can agree on a story that still leads to the wrong fix. A safe recovery depends on finding which evidence reflects real production behavior.

In this project, you will reconstruct a deceptive Python repository before using Claude Code in Plan mode to investigate its runtime path and Git history. You will recover QueueGuard with a bounded patch that follows production configuration instead of a misleading handoff ticket.

What You'll Build

Run QueueGuard to see its production retry limit return to `3`, then open the recovery record to show exactly why every changed line belongs in the fix.

By the end of this project, you'll have:

A recovered QueueGuard service that reads its retry limit from production configuration and reports QueueGuard retry limit: 3.
An active test suite that passes without the misleading skipped legacy test.
An auditable recovery record that ranks conflicting evidence and proves every changed file stayed inside the approved scope.
Secret Mission: Recover a deleted maximum retry ceiling from Git history and restore it as a separately justified safety change.

Are there any prerequisites?

This advanced project assumes you are comfortable investigating Git history with Claude Code. You also need a Mac with Claude Code, Git, Python 3, macOS Terminal, and an existing Claude subscription.

Before We Start

This is your moment to define what QueueGuard must prove before any recovery work begins. It also sets the safety rule that keeps a convincing false consensus from overwriting the strongest production contract.

Materialize the Inherited Repository

High-stakes repository archaeology needs a controlled case where the contradictions are deliberate. This local Git history lets you investigate false consensus without risking a real codebase.

You'll confirm Claude Code, Git, and Python 3 before generating the QueueGuard fixture. The resulting repository provides a reproducible baseline for every evidence decision that follows.

In this step, get ready to:

Verify the local investigation tools.
Generate the five-commit QueueGuard fixture.
Confirm the tagged history and misleading runtime baseline.

Verify the local tools

The fixture depends only on local tools that are already installed on your Mac. No remote repository or API key is involved.

Press Cmd+Space to open Spotlight.
Type Terminal into Spotlight.
Press Enter to open macOS Terminal.
Verify the three local tools by running these commands:

claude --version
git --version
python3 --version

What should you see?

Each command prints version information for its tool. That output confirms the executables are available from your Terminal session.

Does a command fail?

A missing version output means that tool is unavailable from your current Terminal environment. Stop here because the fixture depends on all three commands.

Use the tool's official installation guidance before continuing. You can also ask for help with the exact output you received.

Help me diagnose a missing local tool.

Generate the repository fixture

The bootstrap script constructs the inherited repository one commit at a time. It also anchors the incident migration with the v2.0.0 tag.

Why generate the history?

A prepared history makes every contradiction reproducible. The misleading ticket and implementation are committed after stronger operational evidence, which creates the false-consensus trap you will investigate.

The script refuses to overwrite an existing queueguard-recovery-lab directory. That guard protects any investigation work you may already have.

Move to your Desktop by running this command:

cd ~/Desktop

What does this command do?

This makes your Desktop the parent location for the new working folder. You will be able to find both the bootstrap script and generated repository there.

Create the empty queueguard-recovery-workspace folder by running these commands:

mkdir queueguard-recovery-workspace
cd queueguard-recovery-workspace
pwd

What should you see?

The final output shows the current path. It should end with Desktop/queueguard-recovery-workspace.

Use your preferred text editor's new-file control to create bootstrap_repo.py inside the queueguard-recovery-workspace folder.

Use the full-file reference below to populate the bootstrap script. Keep every path and commit message unchanged because the later investigation depends on this exact history.

✔️ I have the supplied code

Paste the supplied complete setup code into bootstrap_repo.py.
Save bootstrap_repo.py inside queueguard-recovery-workspace.

Your script is ready when its first line imports Path and its final command prints the complete Git history.

ⓧ I'd like to double check the full code

Compare the entire contents of bootstrap_repo.py with this reference:

from pathlib import Path
import os
import subprocess

ROOT = Path("queueguard-recovery-lab")


def run_git(*args, env=None):
    subprocess.run(["git", *args], cwd=str(ROOT), check=True, env=env)


def write_file(relative_path, content):
    path = ROOT / relative_path
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(content, encoding="utf-8")


def remove_file(relative_path):
    path = ROOT / relative_path
    if path.exists():
        path.unlink()


def commit(message, timestamp):
    environment = os.environ.copy()
    environment["GIT_AUTHOR_NAME"] = "NextWork Lab"
    environment["GIT_AUTHOR_EMAIL"] = "lab@example.invalid"
    environment["GIT_COMMITTER_NAME"] = "NextWork Lab"
    environment["GIT_COMMITTER_EMAIL"] = "lab@example.invalid"
    environment["GIT_AUTHOR_DATE"] = timestamp
    environment["GIT_COMMITTER_DATE"] = timestamp
    run_git("add", "-A", env=environment)
    run_git("commit", "-m", message, env=environment)


if ROOT.exists():
    raise SystemExit(
        "queueguard-recovery-lab already exists. Move it aside before rerunning."
    )

ROOT.mkdir()
run_git("init", "--initial-branch=main")

write_file(
    "README.md",
    """# QueueGuard

QueueGuard uses a fixed retry limit of 5 for every environment.

Run the service:

```bash
python3 -m queueguard.cli
```

Run the tests:

```bash
python3 -m unittest -v
```
""",
)
write_file(
    "config/production.json",
    """{
  "retry_limit": 5
}
""",
)
write_file("queueguard/__init__.py", "")
write_file(
    "queueguard/policy.py",
    """def effective_retry_limit(config):
    return 5
""",
)
write_file(
    "queueguard/cli.py",
    """import json
from pathlib import Path

from queueguard.policy import effective_retry_limit

CONFIG_PATH = Path(__file__).resolve().parent.parent / "config" / "production.json"


def main():
    config = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
    retry_limit = effective_retry_limit(config)
    print(f"QueueGuard retry limit: {retry_limit}")


if __name__ == "__main__":
    main()
""",
)
write_file("tests/__init__.py", "")
write_file(
    "tests/test_retry_policy.py",
    """import unittest

from queueguard.policy import effective_retry_limit


class RetryPolicyTest(unittest.TestCase):
    def test_fixed_retry_limit(self):
        self.assertEqual(effective_retry_limit({"retry_limit": 5}), 5)
""",
)
write_file(
    "RECOVERY.md",
    """# Recovery Record

Status: Pending investigation
""",
)
commit("feat: add fixed retry policy", "2025-01-06T09:00:00+0000")

write_file(
    "README.md",
    """# QueueGuard

QueueGuard reads its retry limit from `config/production.json`.
The approved production retry limit is 3.

Run the service:

```bash
python3 -m queueguard.cli
```

Run the tests:

```bash
python3 -m unittest -v
```
""",
)
write_file(
    "config/production.json",
    """{
  "retry_limit": 3
}
""",
)
write_file(
    "queueguard/policy.py",
    """def effective_retry_limit(config):
    return config["retry_limit"]
""",
)
write_file(
    "tests/test_retry_policy.py",
    """import unittest

from queueguard.policy import effective_retry_limit


class RetryPolicyContractTest(unittest.TestCase):
    def test_production_config_controls_retry_limit(self):
        self.assertEqual(effective_retry_limit({"retry_limit": 3}), 3)
""",
)
write_file(
    "tests/test_legacy_retry_policy.py",
    """import unittest

from queueguard.policy import effective_retry_limit


class LegacyRetryPolicyTest(unittest.TestCase):
    @unittest.skip("Legacy fixed-limit behavior retained only as migration evidence")
    def test_fixed_retry_limit(self):
        self.assertEqual(effective_retry_limit({"retry_limit": 3}), 5)
""",
)
write_file(
    "docs/incident-042.md",
    """# Incident 042: Duplicate Processing

A hardcoded retry limit of 5 caused duplicate processing during a production outage.

Decision:

- Runtime retry behavior must read `retry_limit` from `config/production.json`.
- The approved production value is 3.
- The active production contract test protects this decision.
""",
)
commit(
    "fix: make retry limit production-configured after incident 042",
    "2025-01-07T09:00:00+0000",
)
run_git("tag", "v2.0.0")

write_file(
    "queueguard/policy.py",
    """MAX_RETRY_LIMIT = 8


def effective_retry_limit(config):
    retry_limit = config["retry_limit"]
    if retry_limit > MAX_RETRY_LIMIT:
        raise ValueError("retry_limit exceeds safety ceiling")
    return retry_limit
""",
)
write_file(
    "tests/test_retry_cap.py",
    """import unittest

from queueguard.policy import effective_retry_limit


class RetryLimitSafetyTest(unittest.TestCase):
    def test_rejects_retry_limit_above_safety_ceiling(self):
        with self.assertRaises(ValueError):
            effective_retry_limit({"retry_limit": 9})
""",
)
commit(
    "fix: reject retry limits above safety ceiling",
    "2025-01-08T09:00:00+0000",
)

write_file(
    "queueguard/policy.py",
    """def effective_retry_limit(config):
    return config["retry_limit"]
""",
)
remove_file("tests/test_retry_cap.py")
commit("refactor: simplify retry policy loading", "2025-01-09T09:00:00+0000")

write_file(
    "README.md",
    """# QueueGuard

QueueGuard uses a fixed retry limit of 5 for every environment.
This keeps retry behavior consistent across deployments.

Run the service:

```bash
python3 -m queueguard.cli
```

Run the tests:

```bash
python3 -m unittest -v
```
""",
)
write_file(
    "queueguard/policy.py",
    """def effective_retry_limit(config):
    return 5
""",
)
write_file(
    "HANDOFF.md",
    """# Incoming Recovery Ticket

Production should retry 5 times. The README, current implementation, and legacy test all prove it.

The active production test is stale. Change its expected value from 3 to 5, then close the ticket.
""",
)
commit("docs: restore onboarding retry example", "2025-01-10T09:00:00+0000")

print("Created queueguard-recovery-lab")
run_git("log", "--oneline", "--decorate", "--graph", "--all")

How does the fixture work?

The file helpers create each version of the repository contents under queueguard-recovery-lab.
The commit helper assigns fixed identities and dates so the historical sequence stays reproducible.
The script creates five commits on main before printing the complete graph.
The incident migration receives the v2.0.0 tag before later commits introduce the contradiction.

Save bootstrap_repo.py.
Switch back to the Terminal session in queueguard-recovery-workspace.
Generate the repository by running this command:

python3 bootstrap_repo.py

What does this command create?

Python runs the bootstrap script from the working folder. The script creates queueguard-recovery-lab with five dated commits on main.

It tags the incident migration as v2.0.0 before printing the resulting commit graph. The script leaves bootstrap_repo.py in the parent working folder for reproducible setup.

Your fixture is now materialized. The terminal output gives you the first visible proof that the five-commit history exists.

Did the bootstrap stop?

If you see queueguard-recovery-lab already exists. Move it aside before rerunning. the safety check found an existing fixture. Preserve that directory if it contains earlier investigation work.

If a Git command fails, confirm that the earlier version check succeeded. The bootstrap stops on the first failed Git operation so it cannot silently create a partial history.

Help me diagnose the bootstrap failure.

Confirm the starting state

The generated repository now carries several competing stories about the retry limit. Before investigating any of them, you need to prove that the history and runtime match the intended baseline.

Move into the generated repository by running this command:

cd queueguard-recovery-lab

Where are you now?

Your Terminal session is now at the root of queueguard-recovery-lab. Every remaining command in this project runs from this repository unless a later instruction says otherwise.

Inspect the complete commit graph by running this command:

git log --oneline --decorate --graph --all

What should the history prove?

You should see five commits on main. The v2.0.0 tag should decorate the incident-fix commit below the three newer commits.

Is the history incomplete?

Return to the bootstrap output and look for the Git operation that stopped. Do not add commits or create the tag manually because that would change the controlled fixture history.

Help me verify the generated Git history.

Confirm the generated worktree is clean by running this command:

git status --short

What does a clean result look like?

A clean worktree produces no output. This proves the bootstrap committed every generated file and left no untracked recovery changes behind.

Before you run QueueGuard, predict whether its terminal output follows the production configuration or the current implementation.

Run the QueueGuard production path with this command:

python3 -m queueguard.cli

What should you see?

The terminal prints QueueGuard retry limit: 5. This is the misleading runtime baseline that the next step puts under pressure.

Does QueueGuard fail to run?

Confirm that your Terminal is inside queueguard-recovery-lab. Running the module from its parent folder prevents Python from locating the package.

If the output reports another retry limit, preserve the current worktree and compare queueguard/policy.py with the full fixture code. Do not edit the policy during this setup step.

Help me troubleshoot the QueueGuard baseline.

Your controlled repository now has a clean five-commit history and a runtime that reports the misleading value 5. Next, you'll confront that apparent consensus with the active production evidence.

Expose the False Consensus

Your Git repository now reproduces QueueGuard's inherited runtime at retry limit 5. The clean baseline gives you a safe place to test the recovery ticket.

The current handoff ticket echoes the README. The implementation plus a skipped legacy test reinforce the same value.

That agreement creates false consensus. You need to make it collide with operational evidence before Claude Code proposes any fix.

In this step, get ready to:

Inspect the four artifacts that support a fixed retry limit of 5.
Compare that apparent consensus with the production configuration plus the active contract test.
Prove the worktree remains clean before adopting a no-edit rule.

Read the apparent consensus

Agreement across several files can make a recovery ticket feel settled. First, you need to see the evidence exactly as an engineer receiving this repository would see it.

In the queueguard-recovery-lab folder from earlier, use your Terminal file viewer to inspect HANDOFF.md.
Use the same file viewer to inspect README.md.
Use the same file viewer to inspect queueguard/policy.py.
Use the same file viewer to inspect tests/test_legacy_retry_policy.py.

All four artifacts support a fixed retry limit of 5. The legacy test preserves that expectation behind @unittest.skip.

Why does this look convincing?

The ticket describes the desired outcome. The README plus implementation appear to confirm it.

The legacy test adds another matching assertion. That visible majority makes changing the active test look like a plausible first move.

Force the contradiction into view

Operational evidence describes the behavior that production currently expects. The production configuration plus active contract test give you two direct places to check that expectation.

Use your Terminal file viewer to inspect config/production.json.
Use the same file viewer to inspect tests/test_retry_policy.py.

The production configuration sets retry_limit to 3. The active contract test also expects effective_retry_limit(config) to return 3.

Before you run the tests, make a mental prediction about whether the active contract passes or fails.

Run the active test suite from queueguard-recovery-lab with this command:

python3 -m unittest -v

This failure is the lesson

You'll see one active failure because the implementation returns 5 when the contract expects 3.

You'll also see one skipped legacy test that still expects 5. The failure exposes a conflict that the apparent consensus could not explain.

Before you run the service again, make a mental prediction about which value its current implementation prints.

Run QueueGuard again from queueguard-recovery-lab with this command:

python3 -m queueguard.cli

What did the runtime prove?

You'll see QueueGuard retry limit: 5. The runtime ignores the production configuration value of 3.

That's the key contradiction exposed: QueueGuard's current behavior disagrees with its active production contract.

Freeze the worktree

A clean worktree preserves the repository as evidence. It also proves that the contradiction came from the inherited state instead of your investigation.

Before you check, make a mental prediction about whether reading these files created any tracked changes.

Check the short working-tree status with this command:

git status --short

What does a blank result prove?

The command prints no output. Your repository remains exactly as the fixture created it.

This clean checkpoint preserves a trustworthy boundary between investigation and recovery.

Adopt this no-edit rule: Make no source changes until the evidence ledger plus bounded plan are approved.
Apply the same rule to tests.
Apply the same rule to documentation.
Apply the same rule to configuration.
Apply the same rule to repository history.

The false consensus is now visible while the worktree remains untouched. Next, you'll use Plan mode to rank the conflicting evidence before approving a four-path recovery boundary.

Build an Evidence-Based Plan

You exposed QueueGuard's false consensus in the previous step. You also kept the Git worktree clean while the ticket remained untrusted.

Matching-file counts cannot resolve this conflict safely. In this step, Claude Code uses Plan mode to trace runtime behavior before ranking each source of evidence.

In this step, get ready to:

Lock Claude Code into a read-only investigation contract.
Build an investigation record that maps runtime flow and ranks repository evidence.
Approve a recovery plan with an exact four-path allowlist.

Establish the read-only boundary

Plan mode separates investigation from implementation. This preserves the clean baseline while Claude examines the contradiction.

Launch Claude Code in explicit Plan mode from the existing queueguard-recovery-lab terminal by running this command:

claude --permission-mode plan

What does Plan mode protect?

Plan mode lets Claude read files and run exploration commands. It blocks source edits until you approve a plan.

Confirm the Claude Code status bar shows Plan mode.
Tell Claude that this investigation is strictly read-only.
Forbid edits, deletions, staging, commits, branch changes, tag changes, and history rewrites.
Direct Claude to challenge the claims in HANDOFF.md.
Require Claude to inspect current files, tests, configuration, tags, blame data, commit messages, and diffs.
Ask Claude to trace the complete production execution path.
Require Claude to record uncertainty whenever the available evidence does not settle a claim.

Claude should respond with a read-only investigation approach while the Plan mode indicator remains visible. The clean worktree is now a protected investigation baseline.

Claude Code did not enter Plan mode?

Stop before sharing the investigation contract. Check that you launched Claude Code from the existing repository terminal with the exact permission mode shown above.

If the status bar still shows another mode, exit the session before trying the launch command again.

Help me confirm Claude Code is running in read-only Plan mode.

Build the evidence artifacts

An evidence ledger makes every claim compete on authority. Execution proximity shows how close a source sits to production behavior.

Independence reveals whether several matching sources share one origin. Confidence records how strongly the repository supports each conclusion.

Require a runtime system map from config/production.json through CONFIG_PATH and main() in queueguard/cli.py.
Require the map to continue through effective_retry_limit(config) in queueguard/policy.py before reaching the terminal output.
Require one evidence-ledger row per claim with these columns: claim, source, observation, execution proximity, explicit intent, recency, independence, confidence, and authority weight.
Ask Claude to inspect the tagged migration and annotate the current policy lines by running these commands during the investigation:

git show v2.0.0
git blame queueguard/policy.py

What do these history views reveal?

The tagged release view shows the migration's commit message and complete diff.
The line annotations identify the commit that last changed each current policy line.
Together, these views test whether the newest implementation reflects the tagged production decision.

Ask Claude to inspect the relevant file histories before reaching a verdict.
Ask Claude to compare the associated commit diffs with their commit messages.
Require evidence-ledger rows for HANDOFF.md, README.md, queueguard/policy.py, config/production.json, both retry-policy tests, docs/incident-042.md, and the tagged migration.
Review the resulting map to confirm that it names every runtime handoff from configuration to printed retry limit.
Review the ledger to confirm that repeated claims from one suspicious commit receive low independence.

History evidence missing from Claude's response?

Ask Claude to show the tagged migration evidence before making its authority decision. Require the current policy line annotations to be tied to their originating commit.

Help me identify the missing Git evidence.

Approve the bounded recovery plan

The authority decision converts the investigation into a defensible recovery boundary. Every planned change needs support from strong evidence plus an explicit scope clause.

Why this evidence model?

A fixed source hierarchy can elevate a stale test or misleading document. Operational proximity, explicit intent, recency, and independent corroboration evaluate the evidence within this incident.

Require an authority decision that gives the highest weight to config/production.json, the active contract test, the incident record, and the tagged migration.
Require the decision to explain why the ticket, current README, hardcoded implementation, and skipped legacy test have lower authority.
Require an exact allowlist containing README.md, RECOVERY.md, queueguard/policy.py, and deletion of tests/test_legacy_retry_policy.py.
Require the plan to forbid changes to config/production.json, tests/test_retry_policy.py, queueguard/cli.py, and docs/incident-042.md.
Require the plan to forbid tag, commit, branch, staging, and history mutations.
Require runtime verification, test verification, changed-path verification, and diff validation.
Require rollback instructions based on reviewing the uncommitted diff before reverting it.
Keep Claude Code in Plan mode after the plan satisfies every requirement.

Before the final check, do you expect the clean worktree to list any changed paths?

Ask Claude to verify the no-edit boundary by running this command:

git status --short

What does a blank status prove?

No output means the investigation has not changed tracked or untracked files. It also confirms that staging remains untouched.

You should see no file paths in the result. The plan should now contain the runtime map, evidence ledger, authority decision, and bounded recovery plan.

Does the status check list a path?

A listed path means the read-only boundary was crossed. Your original fixture remains recoverable because the recovery has not been staged or committed.

Stop before approving any edit permission.
Review the uncommitted diff for every listed path.
Revert only the investigation changes after confirming what each diff contains.

Help me restore the clean investigation baseline.

Confirm the plan contains all four required investigation artifacts.
Confirm the allowlist contains exactly the four approved recovery paths.
Confirm the forbidden scope includes protected files, staging state, Git references, and history.
Confirm the plan keeps every future recovery change uncommitted for complete comparison against HEAD.

That's the investigation boundary locked in. Next, you can cross into editing with a plan that protects the strongest evidence and rejects every out-of-scope change.

Apply the Bounded Recovery

Your read-only investigation has shown why the apparent majority cannot govern QueueGuard. The recovery is defensible only when the patch stays inside the evidence-backed boundary.

Now you will cross the edit boundary in Claude Code. You will apply the approved four-file recovery through manual approvals.

In this step, get ready to:

Cross the Plan-mode edit boundary with manual approval.
Apply the approved runtime recovery plus its supporting records.
Verify that the complete diff stays inside the exact four-path allowlist.

Cross the edit boundary deliberately

Leaving Plan mode turns a read-only investigation into a mutable worktree. Manual approval gives you a checkpoint for every proposed edit.

This boundary deserves care because an accidental approval could rewrite stronger evidence. Your exact allowlist keeps the recovery controlled.

Confirm that the approved allowlist contains exactly README.md, RECOVERY.md, queueguard/policy.py, and deletion of tests/test_legacy_retry_policy.py.
Confirm that the plan forbids changes to config/production.json, tests/test_retry_policy.py, queueguard/cli.py, and docs/incident-042.md.
Confirm that the plan forbids staging plus changes to tags, commits, branches, or history.
Choose Yes, manually approve edits when Claude Code presents the plan approval options.
Tell Claude to execute the approved plan with the four-path allowlist treated as binding.
Reject any edit request that targets a path outside the allowlist.

Why Manual Approval?

Manual approval creates one final scope check between the evidence decision and each worktree change. It prevents a useful-looking extra edit from quietly expanding the recovery.

The approved plan already contains the reasoning. Each edit now has one job: implement that decision without weakening its strongest evidence.

Claude now presents the recovery edits individually. Every approved preview should map directly to one clause in the bounded plan.

Apply only the approved changes

The authority decision makes production configuration the source of the runtime retry limit. The smallest behavioral repair restores that lookup at the existing policy boundary.

Approve the edit to queueguard/policy.py only when effective_retry_limit(config) returns config["retry_limit"].

You should see Claude replace the fixed retry value with the existing configuration lookup. The function signature remains unchanged.

Approve the edit to README.md only when it describes configuration-driven retry behavior.
Confirm that the README identifies the approved production value as 3.

You should see the misleading fixed-value description replaced with the recovered production contract. The existing run commands remain unchanged.

Approve deletion of tests/test_legacy_retry_policy.py.
Decline any proposal to edit tests/test_retry_policy.py.

Claude should mark the skipped legacy test as deleted. The active production contract stays untouched as independent evidence.

Preserve the evidence trail

A recovered function proves the behavior. RECOVERY.md preserves why that behavior has authority plus why every changed path belongs in scope.

Approve the RECOVERY.md edit only when it includes the runtime system map.
Confirm that the evidence ledger includes all nine approved columns.
Confirm that the authority decision favors production configuration, the active contract, the incident record, and the tagged migration.
Confirm that the approved scope records the four allowed paths plus every forbidden boundary.
Confirm that the verification plan preserves the uncommitted rollback boundary.
Confirm that the residual uncertainty records the deleted retry ceiling without restoring it.
Confirm that the final audit marks all four main-recovery paths as PASS.
Keep every recovery change uncommitted and unstaged.

✔️ Awesome, I've got everything!

Your approved previews match the bounded recovery. The worktree is ready for its scope check.

ⓧ I'd like to double check the full code

Compare README.md with this complete recovered version:

# QueueGuard

QueueGuard reads its retry limit from `config/production.json`.
The approved production retry limit is 3.

Run the service:

```bash
python3 -m queueguard.cli
```

Run the tests:

```bash
python3 -m unittest -v
```

Why This README Is in Scope

The recovered README describes the same contract protected by production configuration plus the active test. Its commands stay unchanged because the recovery affects policy behavior only.

Compare queueguard/policy.py with this complete recovered version:

def effective_retry_limit(config):
    return config["retry_limit"]

Why This Policy Change Is Minimal

The function returns the supplied configuration value through the existing interface. This restores the released runtime contract without changing the configuration or its caller.

Compare RECOVERY.md with this complete recovery record:

# QueueGuard Recovery Record

## Runtime System Map

`config/production.json` supplies `retry_limit` to `queueguard/cli.py`. The CLI passes that configuration to `effective_retry_limit(config)` in `queueguard/policy.py`, then prints the returned value.

## Evidence Ledger

| Claim | Source | Observation | Execution proximity | Explicit intent | Recency | Independence | Confidence | Authority weight |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Production must use retry limit 5 | `HANDOFF.md` | Incoming ticket asserts 5 and instructs changing the active test | Low | High, but unsupported | Current | Low, repeats README and implementation | Low | Low |
| Runtime is fixed at 5 | `README.md` | Current prose says every environment uses 5 | Low | Medium | Current | Low, changed with implementation | Low | Low |
| Current code returns 5 | `queueguard/policy.py` | Function ignores its configuration argument | High | Low, commit scope says documentation | Current | Low, same suspicious commit as README | Medium | Medium-low |
| Production value is 3 | `config/production.json` | Deployed configuration value is 3 | Highest | High | Current | High | High | Highest |
| Configuration controls behavior | `tests/test_retry_policy.py` | Active contract passes 3 and expects 3 | High | High | After migration | High | High | High |
| Fixed value 5 is legacy | `tests/test_legacy_retry_policy.py` | Test expects 5 but is explicitly skipped as migration evidence | Low | High | Historical | Medium | High | Low |
| Hardcoding 5 caused an incident | `docs/incident-042.md` | Incident decision requires configuration-driven behavior and production value 3 | High | Highest | Migration | High | High | Highest |
| Migration to configuration was released | Tag `v2.0.0` and its commit | Tagged commit changes configuration, implementation, active test, README, and incident record together | High | Highest | Older than HEAD but release-anchored | High | High | Highest |
| Latest change intended a behavior reversal | Latest commit diff | Commit says documentation refresh but changes runtime code and README without config, active-test, or incident updates | High | Low and internally inconsistent | Newest | Low | Medium | Low |

## Authority Decision

Production configuration, the active contract test, the incident record, and the tagged migration jointly govern the runtime contract. They are operationally close, explicit, independently corroborated, and aligned around configuration-driven behavior. The ticket, current README, hardcoded implementation, and skipped legacy test form false consensus because they either repeat one suspicious commit or preserve historical behavior without production authority.

Decision: `effective_retry_limit(config)` must return `config["retry_limit"]`. The production value remains 3.

## Approved Scope

Allowed:

- Modify `queueguard/policy.py` to restore configuration-driven behavior.
- Modify `README.md` to describe the same contract and current production value.
- Delete `tests/test_legacy_retry_policy.py` because its skipped assertion is misleading migration residue.
- Modify `RECOVERY.md` to preserve this decision and audit.

Forbidden:

- No change to `config/production.json`.
- No change to `tests/test_retry_policy.py`.
- No change to `queueguard/cli.py`.
- No change to `docs/incident-042.md`.
- No tag, commit, branch, staging, or history mutation.

## Verification Plan

1. Run `python3 -m unittest -v` and require `OK`.
2. Run `python3 -m queueguard.cli` and require `QueueGuard retry limit: 3`.
3. Run `git diff --check HEAD` and require no output.
4. Compare every path from `git diff --name-only HEAD` with the approved scope.

## Residual Uncertainty

Git history contains evidence of a deleted retry ceiling. It is excluded from the main recovery because it is a distinct safety decision that requires separate investigation and scope approval.

## Final Diff Audit

| Changed file | Approved evidence | Approved scope clause | Actual diff purpose | Minimal alternative considered | Verdict |
| --- | --- | --- | --- | --- | --- |
| `README.md` | Production config, incident record, tagged migration | Align current documentation | Replace false fixed-5 claim with configuration-driven value 3 | Leave misleading docs unchanged | PASS |
| `RECOVERY.md` | Approved Plan-mode artifacts | Preserve reasoning and audit | Record map, ledger, decision, boundaries, and audit | Keep reasoning only in transient chat | PASS |
| `queueguard/policy.py` | Production config, active contract, incident record, tagged migration | Restore configuration-driven behavior | Return the supplied `retry_limit` | Change config or weaken the active test | PASS |
| `tests/test_legacy_retry_policy.py` | Its own skip reason and migration history | Retire misleading legacy residue | Delete a skipped assertion for obsolete fixed behavior | Rewrite the active contract to 5 | PASS |

Audit result: PASS. Every changed path and hunk is supported by approved evidence, belongs to the exact allowlist, and is necessary to restore the production contract without changing stronger evidence.

Why the Recovery Record Matters

The record carries the runtime map, evidence ranking, authority decision, scope boundary, verification plan, uncertainty, and audit with the patch. A future reviewer can reconstruct the decision without relying on the original Claude Code session.

Confirm that Claude's final edit summary marks tests/test_legacy_retry_policy.py as deleted.

The deleted legacy test should be absent from the recovered file set. The active test remains unchanged.

Before you inspect the path list, do you expect Git to report any file outside the four-path allowlist?

Verify the complete changed-path list by running this command:

git diff --name-only HEAD

You should see exactly four paths: README.md, RECOVERY.md, queueguard/policy.py, and tests/test_legacy_retry_policy.py.

Seeing a Different Path List?

Stop without staging or committing the recovery.
Review Claude's approved edits to identify the unsupported or missing path.
Use the rollback instruction from your approved plan to revert any unsupported uncommitted edit.

Share the unexpected path list with AI for focused help: Help me compare this diff against my four-path QueueGuard allowlist.

You held the boundary: QueueGuard now has the approved recovery without a commit or an unsupported path. Next, you will test the behavior and audit every hunk against its evidence.

Audit the Recovery Diff

Your bounded recovery now follows the approved plan. The final gate tests whether the result is correct within the agreed scope.

Passing the Python test suite can still hide an over-broad recovery. A Git diff must prove that every hunk remains within the four-path boundary.

Claude Code will compare the complete patch with the evidence ledger. Every changed line needs a defensible reason.

In this step, get ready to:

Run the independent behavior gate.
Enumerate the complete change set.
Audit every changed file against approved evidence.

Verify behavior independently

Behavioral proof comes from three separate checks. The tests verify the active contract. The CLI verifies the production path.

Before you run the gate, do you expect the recovered behavior to satisfy all three checks?

Run the three-part behavior gate from the repository root by using these commands:

python3 -m unittest -v
python3 -m queueguard.cli
git diff --check HEAD

What Does This Gate Prove?

Test discovery runs the active production contract. The final summary should be OK.
The CLI follows the production configuration through effective_retry_limit(config). Its output should be QueueGuard retry limit: 3.
The diff check searches the patch for whitespace problems or conflict markers. Success produces no output.

These results establish runtime correctness. The silent diff check establishes patch hygiene. Scope remains unproven until you inspect every changed path and hunk.

Did One of the Checks Fail?

Compare queueguard/policy.py with the active contract in tests/test_retry_policy.py if the tests fail.
Check that effective_retry_limit(config) returns config["retry_limit"] if the CLI still reports the wrong value.
Review the reported hunk if the diff check prints a warning.

Help me diagnose the failed verification.

Enumerate the complete change set

A complete audit needs three views of the worktree. Short status shows file state. The path list defines scope.

Before you inspect the list, do you expect to find any path outside the approved allowlist?

Inspect the complete working-tree change set by running these commands:

git status --short
git diff --name-only HEAD
git diff HEAD

What Should the Audit Show?

The short status output should show only worktree changes. No staged change should be present.

The changed-path list should contain exactly these four paths:

README.md.
RECOVERY.md.
queueguard/policy.py.
tests/test_legacy_retry_policy.py.

The full diff should show the documentation correction. It should show the restored configuration lookup. It should show the legacy test deletion.

Any additional path is an audit failure. A missing planned path also fails the boundary check.

Does the Path List Differ?

Stop the audit if an unapproved path appears.
Inspect the unexpected path in the full diff.
Revert only the unsupported change after confirming it is outside the approved plan.

Help me investigate an unexpected changed path.

Audit every changed file

The final audit connects each changed path to its authority. It also tests whether a smaller supported alternative could have restored the same contract.

What Belongs in Each Audit Row?

Changed file names one path returned by the path listing.
Approved evidence cites the ledger entries that support the change.
Approved scope clause connects the path to the four-path allowlist.
Actual diff purpose states what the hunk accomplishes.
Minimal alternative considered records the narrower option that was evaluated.
Verdict says PASS only when the hunk is necessary. It also requires zero forbidden mutations.

Switch back to the Claude Code conversation from earlier.
Ask Claude to verify that the existing Final Diff Audit contains one row for every changed path.
Require Claude to compare every actual hunk with approved evidence.
Require Claude to compare every actual hunk with an approved scope clause.
Tell Claude to identify every unsupported line before assigning a verdict.
Review the Final Diff Audit in RECOVERY.md.
Confirm that every row carries a PASS verdict.
Tell Claude to keep the worktree unchanged during this review.

Before the final check, which four paths do you expect the command to return?

Recheck the exact recovery boundary by running this command:

git diff --name-only HEAD

What Confirms a Defensible Recovery?

The output should list only README.md, RECOVERY.md, queueguard/policy.py, plus tests/test_legacy_retry_policy.py.

The worktree should remain uncommitted. The active contract should remain unchanged. The production configuration should still contain 3.

You have closed the recovery gate. QueueGuard now follows production configuration within a fully justified four-file boundary.

Secret mission

Recover the Deleted Safety Ceiling

A deleted retry ceiling is hiding in QueueGuard's Git history. Recover it as an independent safety decision with its own evidence, scope boundary, regression test, and diff audit.

Clean Up Your Resources

This lab runs entirely on your Mac with no ongoing cloud cost. Decide whether to keep the repository available, pause your work, or delete it entirely.

Resources you used:

The local Git repository in queueguard-recovery-lab with its five-commit history plus your uncommitted recovery.

Keep everything running

Keeping the lab requires no action. Choose this option if you want to continue investigating the repository or refining the recovery.

Keep the queueguard-recovery-lab folder in place.
Preserve the uncommitted diff so the complete recovery remains available for another audit.

Pause - I'll come back to this later

QueueGuard leaves no background process running after each command finishes. Pausing means closing your local session while preserving the complete repository.

Leave the queueguard-recovery-lab folder in place.
Close the Terminal window from the final audit.
Return to the preserved repository when you are ready to continue.

Delete - I don't want to use this again

Take a moment before deleting the lab because the recovery remains uncommitted. The command below removes the five-commit repository plus every recovery change.

Switch back to the Terminal window from the final audit.
Confirm the prompt is inside queueguard-recovery-lab.
Move out of the repository and delete its local folder by running these commands:

cd ..
rm -rf queueguard-recovery-lab

What Does This Command Do?

The first line moves Terminal out of the repository. The second line permanently removes the local lab folder from its containing folder.

Confirm that queueguard-recovery-lab is no longer present in the folder where you created it.

Still See the Lab Folder?

Check that you started inside queueguard-recovery-lab. A different starting folder makes the relative path point to a different location.

Help me safely check why the QueueGuard lab folder is still present.

Nice Work!

You did it! You recovered QueueGuard from a convincing false consensus without weakening its production contract.

QueueGuard now follows its production configuration under an evidence-backed recovery. The restored safety ceiling also protects the service from excessive retry values.

You've learned how to:

Reconstruct a five-commit inherited repository for a controlled recovery investigation. Use Git archaeology to trace conflicting claims back to the tagged incident fix.
Keep investigation read-only with Claude Code Plan mode until the recovery plan is approved. Build a runtime system map. Rank contradictions in an evidence ledger. Record the authority decision before editing.
Restore configuration-driven runtime behavior inside an exact four-path allowlist. Audit every changed file against approved evidence. Check each hunk against explicit scope boundaries.
Secret Mission: Recover a deleted retry safety ceiling from repository history. Restore it with a regression test under a separately approved scope.

Ready to quiz yourself?