Logic Guardian

logic-guardian

Purpose

Complex projects (trading bots, payment systems, game engines, state machines) contain interconnected logic that AI agents routinely destroy by accident. The pattern is always the same: new session starts, agent doesn't know existing logic, rewrites or deletes working code, project regresses. logic-guardian breaks this cycle by maintaining a machine-readable logic manifest, enforcing a pre-edit gate on logic files, and validating that edits don't silently remove existing logic. It is the "institutional memory" for business logic.

Triggers

• /rune logic-guardian — manual invocation (scan project, generate/update manifest)
• Auto-trigger: when cook or fix targets a file listed in .rune/logic-manifest.json
• Auto-trigger: when surgeon plans refactoring on logic-heavy modules
• Auto-trigger: when .rune/logic-manifest.json exists in project root

Calls (outbound connections)

• scout (L2): scan project to discover logic files and extract function signatures
• verification (L3): run tests after logic edits to confirm no regression
• hallucination-guard (L3): verify that referenced functions/imports actually exist after edit
• journal (L3): record logic changes as ADRs for cross-session persistence
• session-bridge (L3): save manifest state so next session loads it immediately

Called By (inbound connections)

• cook (L1): Phase 1.5 — when complex logic project detected, load manifest before planning
• fix (L2): pre-edit gate — before modifying any file in the manifest
• surgeon (L2): pre-refactor — before restructuring logic modules
• team (L1): validate logic integrity across parallel workstreams
• review (L2): check if reviewed diff removes or modifies manifested logic

Workflow

Phase 0 — Load Manifest + Invariants

1. Use Read on .rune/logic-manifest.json
2. If file exists:

• Parse manifest, display summary: "Loaded logic manifest: N components, M functions, K parameters"
• Proceed to step 4 (load invariants)

1. If manifest does NOT exist:

• Announce: "No logic manifest found. Scanning project to generate one."
• Proceed to Phase 3 (Generate)

1. Obtain invariants (seeded by onboard — see onboard Step 5.4):

• Preferred: consume the invariants.loaded signal emitted by session-bridge at session start (contains pre-parsed rules[] + stats). No second file read needed.
• Fallback: if no signal was emitted this session, Read .rune/INVARIANTS.md directly and invoke skills/session-bridge/scripts/load-invariants.js to parse.
• Entries come from ## Danger Zones, ## Critical Invariants, ## State Machine Rules, ## Cross-File Consistency, and ## Auto-detected (new). Archived rules are automatically excluded by the loader.
• Each entry follows the WHAT / WHERE / WHY contract from invariants-template.md.
• Treat INVARIANTS.md as the primary source of cross-file rules — the JSON manifest covers component-level signatures; INVARIANTS.md covers rules that span files (shared constants, state transitions, mirrored schemas).
• If the file is absent, log WARN: "INVARIANTS.md not found — run rune onboard to seed baseline rules." Do not block.
• Cache parsed rules keyed by glob so Phase 2 can match the edit target in O(rules × globs) time.

Phase 1 — Validate Manifest Against Codebase

Ensure the manifest matches the actual code (detect drift):

1. For each component in the manifest:

• Use Read on the component's file_path
• Verify each listed function exists (by name + signature match)
• Check if any NEW functions exist in the file that aren't in the manifest

1. Report:

• SYNCED — manifest matches code perfectly
• DRIFT_DETECTED — list specific discrepancies (missing functions, new unlisted functions, changed signatures)

1. If drift detected: ask user whether to update manifest or investigate changes

Phase 2 — Pre-Edit Gate (called by fix/surgeon/cook)

Before ANY edit to a manifested file:

1. Load the manifest (Phase 0)
2. Display the affected component's current spec:

`` COMPONENT: [name] STATUS: ACTIVE | TESTING | DEPRECATED FUNCTIONS: [list with one-line descriptions] PARAMETERS: [configurable values with current settings] DEPENDENCIES: [what other components depend on this] LAST_MODIFIED: [date] ``

1. Require the agent to explicitly state:

• What it intends to change
• What it will NOT change
• Which existing functions/logic will be preserved

1. If the agent cannot list the existing functions → BLOCK the edit. Force a Read of the file first.
2. Cross-file invariant check — for each rule loaded from .rune/INVARIANTS.md in Phase 0:

• If the target file matches any rule's WHERE glob, surface the rule to the agent before the edit proceeds:

`` INVARIANT (from .rune/INVARIANTS.md): WHAT: WHY: ``

• The agent MUST either (a) acknowledge the rule in its plan, or (b) explicitly mark it obsolete and move the entry to ## Archived.
• A matched rule with no acknowledgement → BLOCK in strict preset, WARN in gentle preset.

Phase 3 — Generate Manifest (first-time or rescan)

Scan the project and build the manifest:

1. Use scout to find logic-heavy files:

• Search for files with complex conditionals, state machines, strategy patterns
• Look for files matching: **/logic/**, **/strategy/**, **/engine/**, **/core/**, **/scenarios/**, **/rules/**, **/pipeline/**, **/trailing/**, **/signals/**
• Also search for files with high cyclomatic complexity (many if/else/switch branches)

1. For each discovered file:

• Read the file
• Extract: functions/methods, their parameters, return types, key conditionals
• Classify the component's role: ENTRYLOGIC, EXITLOGIC, FILTER, VALIDATOR, STATE_MACHINE, PIPELINE, CALCULATOR, etc.
• Determine status: ACTIVE (has callers + tests), TESTING (no production callers), DEPRECATED (commented out or unused)

1. Map dependencies between components:

• Which component calls which
• Which share state or config
• Which must be modified together (co-change groups)

1. Write manifest to .rune/logic-manifest.json
2. Save summary to neural memory via session-bridge

Phase 4 — Post-Edit Validation

After any edit to a manifested file:

1. Re-read the edited file
2. Compare against the manifest's function list:

• Any function REMOVED? → ALERT: "Function [name] was removed. Was this intentional?"
• Any function SIGNATURE changed? → WARN: "Signature of [name] changed. Check callers."
• Any PARAMETERS changed? → WARN: "Parameter [name] changed from [old] to [new]. Verify downstream."

1. Run verification to execute tests
2. If all checks pass: update the manifest with new state
3. If function was removed unintentionally: offer to restore from git

Phase 5 — Cross-Session Handoff

Ensure the next session can pick up where this one left off:

1. Update .rune/logic-manifest.json with:

• Current component states
• Last validation timestamp
• Any pending changes or known issues

1. Save key decisions to journal as ADRs
2. Save manifest summary to neural memory:

• "Project X has N active logic components: [list]. Last validated [date]."
• "Component Y was modified: [what changed and why]"

Output Format

Manifest Schema (.rune/logic-manifest.json)

{
  "version": "1.0",
  "project": "project-name",
  "last_validated": "2026-03-05T10:00:00Z",
  "components": [
    {
      "name": "rsi-entry-detector",
      "file_path": "src/scenarios/rsi_entry/detect.py",
      "role": "ENTRY_LOGIC",
      "status": "ACTIVE",
      "functions": [
        {
          "name": "detect_entry_signal",
          "signature": "(df: DataFrame, ticket: Ticket, config: Settings) -> Signal | None",
          "description": "3-step RSI entry detection: challenge -> zone check -> entry point",
          "critical": true
        }
      ],
      "parameters": [
        { "name": "rsi_period", "value": 7, "source": "settings.py" },
        { "name": "challenge_threshold_long", "value": 65, "source": "settings.py" }
      ],
      "dependencies": ["trend-pass-tracker", "indicator-calculator"],
      "dependents": ["production-worker", "backtest-engine"],
      "last_modified": "2026-03-01",
      "last_modifier": "human",
      "checksum": "sha256:abc123..."
    }
  ],
  "co_change_groups": [
    {
      "name": "entry-pipeline",
      "components": ["trend-pass-tracker", "rsi-entry-detector", "indicator-calculator"],
      "reason": "These components share RSI parameters and must be modified together"
    }
  ]
}

Validation Report

## Logic Guardian Report

### Manifest Status: SYNCED | DRIFT_DETECTED
- Components: N active, M testing, K deprecated
- Last validated: [timestamp]

### Pre-Edit Gate
- File: [path]
- Component: [name] (ACTIVE)
- Functions preserved: [list]
- Intended change: [description]
- Impact: [downstream effects]

### Post-Edit Validation
- Functions removed: [none | list]
- Signatures changed: [none | list]
- Parameters changed: [none | list]
- Tests: PASS | FAIL
- Manifest: UPDATED | NEEDS_REVIEW

Constraints

1. MUST load manifest before ANY edit to a manifested file — the entire point is pre-edit awareness
2. MUST NOT allow edits to ACTIVE logic without the agent explicitly listing what will be preserved — prevents silent overwrites
3. MUST alert on function removal — the #1 failure mode is deleting working logic
4. MUST run tests after editing manifested files — logic changes without test verification are blind
5. MUST update manifest after validated edits — stale manifests provide false confidence
6. MUST NOT auto-generate manifest for files the agent hasn't read — manifest must reflect actual understanding

Mesh Gates

| Gate | Requires | If Missing | |------|----------|------------| | PREEDIT | .rune/logic-manifest.json loaded + component spec displayed | BLOCK edit. Run Phase 0 + Phase 2 first. | | POSTEDIT | All manifest functions still present OR removal explicitly acknowledged | ALERT + offer git restore | | CROSS_SESSION | Manifest updated + summary saved to journal/nmem | WARN: next session will lack context |

Sharp Edges

| Failure Mode | Severity | Mitigation | |---|---|---| | Agent edits manifested file without loading manifest first | CRITICAL | Phase 2 gate: cook/fix MUST call logic-guardian before editing manifested files | | Manifest drifts from actual code (manual edits not tracked) | HIGH | Phase 1 validation on every load — detect and reconcile drift | | Agent acknowledges existing logic but still overwrites it | HIGH | Post-edit Phase 4 diff check catches removed functions regardless of agent claims | | Manifest becomes too large (100+ components) | MEDIUM | Group related functions into composite components; track at module level not function level | | False sense of security — manifest exists but is outdated | MEDIUM | Checksum comparison on every load; warn if file hash doesn't match manifest | | Agent treats manifest generation as a one-time task | LOW | Phase 5 cross-session handoff ensures manifest stays alive across sessions |

Done When

• .rune/logic-manifest.json exists and passes Phase 1 validation (SYNCED)
• All manifested components have status (ACTIVE/TESTING/DEPRECATED) and function listings
• Pre-edit gate blocks edits without manifest awareness (Phase 2 enforced)
• Post-edit validation confirms no unintended function removal (Phase 4 passed)
• Manifest summary saved to journal + neural memory for cross-session handoff
• Tests pass after any logic edit

Returns

| Artifact | Format | Location | |----------|--------|----------| | Logic manifest | JSON | .rune/logic-manifest.json | | Validation report (SYNCED / DRIFT) | Markdown | inline | | Pre-edit gate summary | Structured text | inline | | ADR entries for logic changes | Markdown | via journal L3 |

Cost Profile

~1,000-2,000 tokens for manifest load + pre-edit gate. ~3,000-5,000 tokens for full project scan (Phase 3). Sonnet for code analysis; haiku for file scanning via scout.

Scope guardrail: logic-guardian protects existing logic — it does not implement new features or refactor code.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Rune-kit
• Source: Rune-kit/rune
• License: MIT

Install and usage instructions live in the source repository linked above.