logic-guardian
Protects complex business logic from accidental deletion or overwrite. Use when editing payment, trading, state-machine, or other load-bearing business logic where a single deleted line can cause silent data corruption. Maintains a logic manifest, enforces pre-edit gates, validat
Install
npx skills add https://github.com/Rune-kit/rune/tree/master/skills/logic-guardian
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install rune-kit-rune@llmmart
git clone https://github.com/Rune-kit/rune.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole rune-kit/rune collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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
cookorfixtargets a file listed in.rune/logic-manifest.json - Auto-trigger: when
surgeonplans refactoring on logic-heavy modules - Auto-trigger: when
.rune/logic-manifest.jsonexists in project root
Calls (outbound connections)
scout(L2): scan project to discover logic files and extract function signaturesverification(L3): run tests after logic edits to confirm no regressionhallucination-guard(L3): verify that referenced functions/imports actually exist after editjournal(L3): record logic changes as ADRs for cross-session persistencesession-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 planningfix(L2): pre-edit gate — before modifying any file in the manifestsurgeon(L2): pre-refactor — before restructuring logic modulesteam(L1): validate logic integrity across parallel workstreamsreview(L2): check if reviewed diff removes or modifies manifested logic
Workflow
Phase 0 — Load Manifest + Invariants
- Use
Readon.rune/logic-manifest.json - If file exists:
- Parse manifest, display summary: "Loaded logic manifest: N components, M functions, K parameters"
- Proceed to step 4 (load invariants)
- If manifest does NOT exist:
- Announce: "No logic manifest found. Scanning project to generate one."
- Proceed to Phase 3 (Generate)
- Obtain invariants (seeded by
onboard— see onboard Step 5.4):- Preferred: consume the
invariants.loadedsignal emitted bysession-bridgeat session start (contains pre-parsedrules[]+ stats). No second file read needed. - Fallback: if no signal was emitted this session,
Read.rune/INVARIANTS.mddirectly and invokeskills/session-bridge/scripts/load-invariants.jsto 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 / WHYcontract frominvariants-template.md. - Treat
INVARIANTS.mdas 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 onboardto 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.
- Preferred: consume the
Phase 1 — Validate Manifest Against Codebase
Ensure the manifest matches the actual code (detect drift):
- For each component in the manifest:
- Use
Readon the component'sfile_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
- Use
- Report:
SYNCED— manifest matches code perfectlyDRIFT_DETECTED— list specific discrepancies (missing functions, new unlisted functions, changed signatures)
- 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:
- Load the manifest (Phase 0)
- 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] - Require the agent to explicitly state:
- What it intends to change
- What it will NOT change
- Which existing functions/logic will be preserved
- If the agent cannot list the existing functions → BLOCK the edit. Force a
Readof the file first. - Cross-file invariant check — for each rule loaded from
.rune/INVARIANTS.mdin Phase 0:- If the target file matches any rule's
WHEREglob, surface the rule to the agent before the edit proceeds:INVARIANT (from .rune/INVARIANTS.md): WHAT: <rule.what> WHY: <rule.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
strictpreset, WARN ingentlepreset.
- If the target file matches any rule's
Phase 3 — Generate Manifest (first-time or rescan)
Scan the project and build the manifest:
- Use
scoutto 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)
- For each discovered file:
Readthe file- Extract: functions/methods, their parameters, return types, key conditionals
- Classify the component's role: ENTRY_LOGIC, EXIT_LOGIC, FILTER, VALIDATOR, STATE_MACHINE, PIPELINE, CALCULATOR, etc.
- Determine status: ACTIVE (has callers + tests), TESTING (no production callers), DEPRECATED (commented out or unused)
- Map dependencies between components:
- Which component calls which
- Which share state or config
- Which must be modified together (co-change groups)
- Write manifest to
.rune/logic-manifest.json - Save summary to neural memory via
session-bridge
Phase 4 — Post-Edit Validation
After any edit to a manifested file:
- Re-read the edited file
- 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."
- Run
verificationto execute tests - If all checks pass: update the manifest with new state
- 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:
- Update
.rune/logic-manifest.jsonwith:- Current component states
- Last validation timestamp
- Any pending changes or known issues
- Save key decisions to
journalas ADRs - 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
- MUST load manifest before ANY edit to a manifested file — the entire point is pre-edit awareness
- MUST NOT allow edits to ACTIVE logic without the agent explicitly listing what will be preserved — prevents silent overwrites
- MUST alert on function removal — the #1 failure mode is deleting working logic
- MUST run tests after editing manifested files — logic changes without test verification are blind
- MUST update manifest after validated edits — stale manifests provide false confidence
- MUST NOT auto-generate manifest for files the agent hasn't read — manifest must reflect actual understanding
Mesh Gates
| Gate | Requires | If Missing |
|---|---|---|
| PRE_EDIT | .rune/logic-manifest.json loaded + component spec displayed |
BLOCK edit. Run Phase 0 + Phase 2 first. |
| POST_EDIT | 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.jsonexists 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.
Files (rune)
-
SKILL.md 12.6 KB
--- name: logic-guardian description: "Protects complex business logic from accidental deletion or overwrite. Use when editing payment, trading, state-machine, or other load-bearing business logic where a single deleted line can cause silent data corruption. Maintains a logic manifest, enforces pre-edit gates, validates post-edit diffs." metadata: author: runedev version: "0.3.0" layer: L2 model: sonnet group: quality tools: "Read, Write, Edit, Glob, Grep" listen: invariants.loaded --- # 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) 3. If manifest does NOT exist: - Announce: "No logic manifest found. Scanning project to generate one." - Proceed to Phase 3 (Generate) 4. 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 2. Report: - `SYNCED` — manifest matches code perfectly - `DRIFT_DETECTED` — list specific discrepancies (missing functions, new unlisted functions, changed signatures) 3. 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] ``` 3. Require the agent to explicitly state: - What it intends to change - What it will NOT change - Which existing functions/logic will be preserved 4. If the agent cannot list the existing functions → BLOCK the edit. Force a `Read` of the file first. 5. **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: <rule.what> WHY: <rule.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) 2. For each discovered file: - `Read` the file - Extract: functions/methods, their parameters, return types, key conditionals - Classify the component's role: ENTRY_LOGIC, EXIT_LOGIC, FILTER, VALIDATOR, STATE_MACHINE, PIPELINE, CALCULATOR, etc. - Determine status: ACTIVE (has callers + tests), TESTING (no production callers), DEPRECATED (commented out or unused) 3. Map dependencies between components: - Which component calls which - Which share state or config - Which must be modified together (co-change groups) 4. Write manifest to `.rune/logic-manifest.json` 5. 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." 3. Run `verification` to execute tests 4. If all checks pass: update the manifest with new state 5. 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 2. Save key decisions to `journal` as ADRs 3. 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`) ```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 | |------|----------|------------| | PRE_EDIT | `.rune/logic-manifest.json` loaded + component spec displayed | BLOCK edit. Run Phase 0 + Phase 2 first. | | POST_EDIT | 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.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.