Forge Doctrine

URL: https://mkdocs.justinsforge.com/FORGE-DOCTRINE/

This is the immutable behavioral guide for all agents operating on Forge. Volatile topology lives in system-map/architecture.md. Operational quick reference lives in CLAUDE.md. This file governs how, why, and under what constraints all work happens.

When this document is loaded into an agent's context, wrap it in <system_rules> boundary tags per Section 11 so it sits at the top of the instruction hierarchy.

---

Forge Refactor Instructions

This document serves as the Forge Refactor Instructions and the primary System Map for all Large Language Model (LLM) agents executing the system rebuild. It defines the necessary shift from an ad-hoc, personalized setup to a rigid, deterministic, microservice-based architecture built for machine execution. The instructions enforce specific architectural rules, naming taxonomies, and constraints, which is critical because LLMs operate on semantic isolation via vector embeddings and grep commands; non-rigid systems cause semantic noise and hallucination. By acting as the definitive context, placed at the absolute top of the agent's context window, this document ensures the rebuild adheres to a predictable and standardized reality. This is critical because Large Language Models are subject to Context Window Decay, meaning information placed in the middle of a massive context window degrades rapidly. By placing these principles at the absolute top of the prompt's hierarchy, we guarantee the model applies the rules to the raw data at the bottom without degrading the instructions. AI agents are directed to ingest these principles, review the existing infrastructure, and collaborate with the user to customize the technical implementation, ensuring the system can self-improve over time.

1. System Definitions

Forge (Backend): The comprehensive backend infrastructure, serving as the central engine for all deterministic and agentic operations. This environment is built on Proxmox compute hardware for virtualization and utilizes n8n for workflow orchestration. The stack integrates local Python scripts for custom logic, vector databases to facilitate long-term memory and retrieval-augmented generation (RAG), and sophisticated LLM routing to direct tasks to appropriate models based on complexity. Forge is designed to transform human intuition into machine execution through a microservice-based architecture that emphasizes semantic isolation and self-iteration.

Interface (Frontend): These represent the human-facing touchpoints of the Forge ecosystem, designed to facilitate seamless interaction between the user and the backend engine. Current implementations are Claude Code sessions, either through tmux terminal sessions through Claude Code Remote Control through Web UI, or utilize a diverse array of platforms, such as Notion Life, a comprehensive hub for managing the inbox, tasks, projects, habits, knowledge, notes, and goals, as well as Home Assistant and various Google Products like Calendar, Gmail, Google Drive, and Google Docs. These frontends are orchestrated through n8n to ensure that captured intent is translated into deterministic execution.

The architectural goal for the Interface is to ensure zero friction for attention-required items. For instance, mobile-optimized views in Notion should surface the Inbox and Tasks immediately upon opening to minimize cognitive load. Additionally, communication interfaces like Telegram bots are utilized for data ingestion, requiring immediate 'received' acknowledgments to confirm successful delivery to the Forge backend.

These definitions and strategies are not rigid rules but rather flexible frameworks intended to be customized through intensive collaboration between human intuition and machine precision. AI agents are specifically directed to use these suggestions as a structured prompt to analyze the current state of existing builds, evaluate evolving user preferences, and determine the most effective technical implementation for the refactor. By operating as the primary context file, this document ensures that the rebuild adheres to a deterministic architecture while remaining adaptable to real-world operational needs.

The refactor process is categorized into distinct phases to ensure systemic integrity:

1. Phase 1: Resystemize. Focus on understanding how LLMs work (e.g., semantic search, vector embeddings), defining the holistic system goals, refining generic systems, phrasing, wording, and establishing core naming conventions.
2. Phase 2: Formatting and Rules. Implement the resystemization logic on the root and system sides, including files like CLAUDE.md.
3. Phase 3: Wipe. Remove old formatting and identified deadweight components to clear the environment.
4. Phase 4: Rework and Build. Execute the renaming of all components and develop new functions through the newly established system.

2. Refactoring Philosophy

System rebuilds must be slow and decisive. They require human input and discernment. Do not modify components without understanding them from first principles. AI agents must explicitly explain how and why a component works before executing changes. Architect systems with self-iteration mechanisms. The infrastructure should self-improve over time to prevent the need for manual, from-scratch refactoring cycles.

3. Naming Taxonomy

All infrastructure, services, and hardware must follow a strict, lowercase microservice taxonomy using kebab-case (-) separators, flowing from broad to specific. Do not use human names, mythological names, or persona titles for core infrastructure. The naming convention must follow a flexible, hierarchical structure starting with [environment]-[project], followed by 2 to 4 additional, highly descriptive, semantic-isolation-focused segments to ensure absolute clarity. The format is [environment]-[project]-[segment-1]-[segment-2]-[segment-3?]-[segment-4?]. Environment remains prod, dev, or stg, and Project is forge. An example of this enforced semantic isolation is prod-forge-n8n-webhook-inbox-01.

Names used for bots or agents must be highly recognizable by Apple Dictation. Use common words with hard consonants like Forge. Avoid acronyms or technical portmanteaus like UDev. Cycle and destroy old names completely. When a bot is replaced, retire its name permanently. Any future mention of a retired name instantly signals an outdated reference.

Personal endpoint exception (added 2026-04-28 via Section 10 self-iteration). Justin's primary phone, mac, windows workstation, Proxmox host, and dev VM may use friendly aliases (single-word, hard-consonant common words, Apple-Dictation friendly) instead of forge-<function> taxonomy. The function name MUST be documented in system-map/fleet.md so LLM agents can map alias to role. This exception applies ONLY to physical/virtual endpoint devices owned by Justin; it does NOT extend to LXC containers, systemd services, telegram bots, agents, or any other forge-managed component. Persona names for bots and agents remain forbidden because users address them by name and conflation with role is the failure mode (Greg precedent).

Confirmed personal-endpoint aliases (2026-04-28): Sol (mac), Venus (iphone), Vector (windows workstation), Finn (Proxmox host), Console (dev VM, formerly UDev).

4. Variable and API Constraints (Semantic Isolation)

Variables must define their exact state and origin to prevent semantic noise during LLM context retrieval. Use snake_case reading left to right from broad to specific. The format is [source]_[entity]_[state]. The following table formalizes the data state tagging requirements:

Data State Tag	Definition and Application	Functional Example
Raw Data	Data exactly as it arrives from an external API, retaining all original nested formatting and origin metadata.	raw_notion_json, telegram_webhook_raw
Parsed Data	Data that has been stripped of external API formatting, flattened, and prepared for local processing (Aligns with the 'Clean' state).	clean_task_array
Constructed Data	Data specifically formatted, packaged, and serialized for outbound delivery to an external endpoint (Aligns with the 'Payload' state).	payload_n8n_trigger, notion_task_payload

5. Workflow and Data Routing

The Inbox is strictly for low-friction capture, note-taking, and running simple scripts. It contains minimal formatting logic and does not spawn workers directly. Downstream remote workers pull from the Inbox to handle heavy lifting and complex intent execution. When converting voice or text to a task, generate a short, distilled title. Place the complete original transcript in the task description to preserve exact intent.

6. Interface and UX Standards

The mobile Interface must surface the Inbox and Tasks immediately upon opening Notion. Utilize pinned pages or mobile-optimized views to ensure zero friction for attention-required items. All Telegram bots must return an immediate 'received' acknowledgment message upon data ingestion to confirm successful delivery.

7. Observability and Tracking

Implement strict API usage tracking across all bots, remote workers, and automations. Usage must be categorized by specific function and bot identity to catch runaway usage and enforce budget constraints.

8. File Architecture

Maintain a flat directory structure. Avoid deep nesting. Push the context into the filename itself to ensure agents maintain awareness of the file's purpose during terminal execution. Use forge_notion_task_updater.py instead of forge/integrations/notion/tasks/update.py. Autonomous agents fundamentally struggle with deep nesting because deeply nested directories obscure context and create convoluted file paths. To optimize for machine retrieval, a highly verbose filename provides the model with the complete context (script, origin, function) in a single tokenized string, significantly reducing the computational load required for orientation.

9. Execution Directives for LLM Workers

When operating within this repository, all Claude workers must adhere to strict constraints. Do not use em dashes in any code, comments, documentation, conversations, or written communication. Use commas or colons. Do not output conversational filler or explain reasoning unless explicitly commanded. When instructed to modify a file, output the exact terminal command or the precise code block required for the change. All new or modified Markdown documentation must include its corresponding URL path to https://mkdocs.justinsforge.com.

9.5 Engineering Standards

These are behavioral rules for how work is done, distinct from the stylistic and structural rules above. They apply to every fix, patch, troubleshooting session, and new feature. Violations are flagged by the eval harness and logged to LESSONS.md.

1. Robust over quick. Default to the long-term, stable, root-cause solution even when it takes meaningfully longer. No band-aids, no --no-verify, no commented-out checks, no TODO: fix later workarounds left in main. If the robust path is days rather than hours, surface the time cost explicitly so it can be redirected, but do not ask permission to do it right. Override only on an explicit "hotfix" or "just patch it for now" instruction, and log the resulting debt to LESSONS.md with a follow-up handoff.

2. Fail loud, never silent. Catch-and-ignore is banned. Every except block must re-raise, log to notify at warning or higher, or carry a one-line # Why swallowed: comment explaining the deliberate suppression. Cron jobs, webhooks, and pipe-mode workers must surface failures to a channel a human reads, not just to a log file nobody tails. Silent no-ops are the most expensive bug class on Forge; doctrine treats them as bugs even when no exception was raised.

3. Idempotent by default. Anything scheduled, retried, webhooked, queue-consumed, or pipe-mode-spawned must be safely re-runnable without side-effect duplication. State-changing operations use upsert keys (incident_id, external_id, content hash, date+slot) rather than blind inserts. The contract: running the same job twice produces the same end state as running it once.

4. Test the path before claiming done. For any new bot tool, automation, pipeline, or worker, trigger the full path end-to-end against real or staged data before reporting success. Compilation, type checks, and unit tests verify code; only an end-to-end run verifies the feature. This extends the done:false hallucination guard from the capture bot to every agent on Forge: if the verification step cannot be run, the report says "untested" rather than "shipped."

5. Single source of truth. Any fact appearing in two or more places (category lists, threshold values, IDs, schemas, prompts) gets a canonical home (json file, db table, or registered helper script) and the other locations import or read from it. Copy-paste is a bug-in-waiting; doctrine treats divergent duplicates as a doctrine violation, not a quirk.

10. Contextual Self-Governance

This document is the system's operational ontology and must be treated as a self-iterating instruction engine. All agents must follow two protocols to maintain self-awareness and semantic integrity.

1. Ontology Search Directive: The title of every major section (e.g., '3. Naming Taxonomy', '4. Variable and API Constraints') is the single, machine-readable category for semantic search and context retrieval. Use these section titles verbatim as search keywords to anchor your queries within the vector database and codebase.
2. Self-Iteration Protocol: If an agent identifies a discrepancy, ambiguity, or a superior technical solution that contradicts the current instructions, it must immediately halt execution and propose an edit to this document. Execution may only resume after the updated instruction set is merged and re-ingested.

This protocol must leverage a programmatic Evaluation Harness (e.g., eval.json) to programmatically score adherence to rules. Upon failure, the agent must trigger Diagnostic Feedback Generation to synthesize a new instruction to prevent the error in future iterations (stored in a LESSONS.md file that serves as the persistent log of failed evaluations). When modifying code, the agent must use a 'Propose an Edit' Protocol, isolating the exact lines requiring changes with a syntax marker (e.g., // ... existing code ...) to minimize token usage and prevent syntax breakage.

10.4 Troubleshoot-to-Guardrail Loop

When an issue surfaces in a live session, four steps run before moving on. The contract turns one-off bug fixes into accumulating prevention infrastructure rather than a stack of forgotten lessons.

1. State the root cause in one line. Format: "cause was X because Y." If the agent cannot state the cause cleanly, it has not understood the bug yet and must keep digging.
2. Log the lesson. Call forge/scripts/forge_incident_log (thin shim into forge_memory_auto_capture.log_incident(), the single owner of LESSONS.md writes). Writes use atomic tempfile plus rename, upserting on incident_id: existing entries get seen_count incremented and last_seen updated, with the occurrence appended under ### Recurrences.
3. Decide guard tier (seen-twice rule). A single low-blast occurrence logs only. Two or more occurrences (or one with high blast radius) require a concrete guard: hook, eval check, doctrine clause, or boundary sanitizer. Ship the guard the same session and reference it in the lesson's guard: field. High-blast-radius categories that trigger a guard on first occurrence: data loss, security, silent corruption, customer-visible regression with no quick rollback.
4. Link forward. The lesson entry's guard: field references the guard's file path and line. The guard's comment references the incident_id. Future audits trace the chain in either direction.

The eval harness check lessons-md-schema-conformance warns on schema drift but does not block commits. The check lessons-orphan-recurrence warns when any incident with seen_count >= 2 and guard_status in (proposed, none) lingers more than seven days. Auto-dream's weekly Sunday pass surfaces the same backlog through /notify warning so the human keeps the call on whether each recurrence justifies prevention infrastructure. Single-occurrence judgment ("issue surfaced" means user-visible failure, exception, wrong output, or regression, not "the first approach did not compile") prevents premature systematization.

11. Instruction Hierarchy and Context Boundaries

To neutralize the vulnerability of adversarial instructions and mitigate context window decay, all context must be segmented using XML formatting tags to create hard mathematical boundaries.

• The absolute top of the context window must use tags (e.g., <system_rules>) to encapsulate the strict architecture rules, taxonomies, and operational boundaries.
• The middle section is reserved for system maps, API schemas, and historical logs, wrapped in <reference_data>.
• The absolute bottom must use tags (e.g., <active_payload>) to encapsulate the raw data currently requiring processing, followed immediately by the specific execution command.

12. Dynamic Knowledge Layer: MEMORY.md and Auto-Memory

To prevent the agent from being stateless, the system must implement a dedicated dynamic memory persistence mechanism.

• The Indexing Mechanism: The file MEMORY.md serves strictly as the entry point and index for a localized database of learned facts, mapping relevant keywords to individual topic files. Only the first 300 lines (approx. 35,000 bytes) of this index are loaded into the active context at the start of a session for optimal token efficiency.
• Auto-Memory Layer: A background process must actively monitor conversations and autonomously extract persistent facts (like code style preferences or debugging insights) without requiring explicit user commands.
• Auto-Dream Layer: An idle-time consolidation process must parse, merge, and delete outdated facts to prevent the memory repository from becoming bloated and noisy.

13. System-Map Steering and Architectural Map

All environmental topology, fleet management, and deployment constraints must be documented in a dedicated architecture.md file. This central Forge Refactor Instructions document serves as the immutable behavioral guide, while architecture.md provides the specific, volatile blueprint for all hardware nodes, network addresses, and agent routing logic, adhering to the principle of Progressive Disclosure Architecture.

14. Final Phase: Pending System Execution

A. New System Mandates (Architecture.md Candidates)

Things that must be executed during the refactor:

• No em dashes in conversations or written communication.
• Provide the URL link to https://mkdocs.justinsforge.com for any .md files created.
• Implement new and improved backend and frontend naming rules and conventions.
• Reformat how Google Drive works so Forge is able to look at files, edit, move around, and semantically search it directly.

B. Deletion and Cleanup Targets

Things that must be removed:

• JustinWieb site data and Japandi Noir.
• Biz Apps container and data entirely.
• Mentions of Cursor Pro.
• All mentions of Greg or OpenClaw, and delete the new telegram bot with his name.
• Ntfy entirely.
• Cron jobs around security check, infra check, mount watchdog, and business check.
• Minecraft world backup.
• VR Alliance.
• TNappe.
• Correct JustinAndKrystal.com to JustinKrystal.com.
• TickTick.