Repository navigation
Design Principles
언어: 🇺🇸 English | 🇰🇷 한국어
Ghost-ALICE aims to make the assistant's work consistently more dependable by preserving the user's actual objective, comparing results with original evidence, and correcting mismatches. The design objective is a higher quality floor for that work. A procedure, authenticated record, or passing individual check does not by itself establish that the user's requested result is correct.
Ghost-ALICE is designed for a cooperative responding model that follows the user's instructions and the installed contract. It catches that model's mistakes, omissions and drift.
The current-session assistant is the model responding in the native conversation. It constructs a provisional work plan, performs authorized actions, judges the results against their references, and revises the affected work when the comparison supplies a reason. The assistant can change a procedure it selected when that procedure obstructs the user's objective. Checks that the user or the installed contract requires stay required, and a required check that cannot run leaves its criterion unresolved. More gates, more repetition, and longer prompts are not objectives.
Except for the user and host boxes, the decisions in this diagram belong to the model responding in the current conversation. Arrows carry the result, evidence or condition used for the next decision. Actual review-file transport and storage follow the host-tool path in the architecture.
flowchart TB
U["User: objective, constraints and permission"] -->|"Input as is (user-said)"| I["Model: interpret the input (interpreted-as):<br/>objective, constraints and done conditions"]
I -->|Interpretation and its assumptions| Q{"Does an assumption the user did not state<br/>change the next action?"}
Q -->|Yes| K["Model: end the answer with a question that states<br/>the assumption and what changes if it is wrong"]
K -->|Confirmation question| U
Q -->|No; the intent is clear| P["Model: choose work and relevant references"]
P -->|Tool requests within authority| H["Host: execute permitted tools"]
H -->|Actual observations and original sources| A["Model: draft the answer from the results"]
A -->|Draft claims and source contents| C["First judgment: compare each claim<br/>with its original evidence"]
C -->|Claim verdicts, sources and reasons| CW["Second judgment: compare the whole answer<br/>with the objective and constraints"]
I -->|Interpreted objective, constraints and done conditions| CW
CW -->|Conflicts, omissions and supported results| M{"Does a mismatch affect a required<br/>result or dependency?"}
M -->|Yes| R["Investigate enough to select the affected correction"]
R -->|Needed authorized action is available| P
R -->|No justified action or prerequisite unavailable| N["Retain supported results and report<br/>the unresolved requirement"]
M -->|No; retain nonessential unresolved details| S{"Does positive evidence support<br/>every required criterion, including the whole result?"}
S -->|Yes| D["Report the supported result"]
S -->|No| N
N -->|Independent authorized work is available| P
N -->|Supported results and unresolved requirements| U
D -->|Supported result| U
D -->|Changed evidence| P
Every input passes through interpretation before the model chooses work. The input as is (user-said: ) stays in the host transcript. The model's interpretation (interpreted-as: ) holds the objective, constraints and done conditions. For work that needs tools, the model records a new or changed interpretation before the first tool call. When an assumption the user did not state would change the next action, the model ends its answer with a confirmation question that states the assumption and what changes if it is wrong. The user's answer arrives as a new input. The second judgment compares the whole answer with this interpretation.
A mismatch identifies an observation to assess; it does not prove where the cause lies or require recovery. When the objective and required dependencies are unaffected, the assistant may leave the detail unresolved or omit nonessential work. When correction is needed, it may widen its focus to a dependency or premise and then narrow its focus to the affected action after investigating the cause. Revising affected work does not require restarting every completed step. The assistant preserves valid unaffected results, original sources and original verification times.
The absence of an observed mismatch does not prove completion. The assistant must have positive support for the required criteria, including criteria for the combined result. A correct part can remain useful while the whole task is unresolved.
The assistant chooses what to examine. The task complexity level follows from the work's verification burden, and the level's own check always runs; beyond it, the assistant runs another check only when that check's outcome can change the next action or a criterion's judgment. Focus and recovery defines micro, meso, macro and meta and the movement between them. Verification and evidence defines comparison and the decision to perform another check. A wider focus does not automatically require more checks; a narrowly scoped claim can require demanding verification.
The assistant following Core instructions judges meaning and evidence. Core code authenticates the submitted records and their bindings; it does not turn a recorded judgment into guaranteed truth. Core keeps a procedural floor at Stop: it compares the completion claim in the answer with the recorded review and the remaining necessary work. When the claim lacks that support or necessary work remains, Core reports how far the work got and the recorded necessary work, and the host stops. Core does not start another turn. The native host invokes the model, tools and hooks and enforces tool permission. The system architecture maps these responsibilities to the implementation.
The philosophy is implemented and operated inside one structure, and each boundary in it follows from the philosophy.
flowchart TB
U["User<br/>supplies the objective and authority"]
subgraph GA["Ghost-ALICE"]
C["Core: how the generative backend works under this philosophy<br/>common contract, skills and procedures,<br/>Core code (hooks, ledger, context gateway)"]
subgraph AD["Adapters: one per host, no rule of their own"]
AC["for Claude Code"]
AX["for Codex"]
end
end
subgraph OUT["Outside Ghost-ALICE: cannot be forced"]
HC["Host app: Claude Code"] -->|"model requests"| BC["Generative backend: Claude"]
HX["Host app: Codex"] -->|"model requests through the context gateway"| BX["Generative backend: GPT"]
end
X["Add-on such as Autopilot<br/>outside Core, attaches its action after the notice"]
P["The project's way of building<br/>contributing guide"]
C -->|"translated without restating its rules"| AD
AC -->|"installed into"| HC
AX -->|"installed into"| HX
U -->|"input; the model confirms the intent first: the starting point"| HC
U -->|"input"| HX
C -.->|"instructions and records only;<br/>blocks no tool; its failure never stops the work"| OUT
C -.->|"Stop notice anyone can read"| X
P -->|"builds and changes it, from outside"| GA
Read the figure from Core outward. Core is the collection of how the generative backend works under this philosophy: the common contract, the skills and procedures, and the Core code (hooks, ledger and context gateway). An adapter translates Core for one host and adds no rule of its own. The installer already puts the one common contract into a Claude Code template and a Codex template, and each template adds only that host's mechanics, so supporting another host, such as Gemini, means adding one adapter. The far side of an adapter is the host app, not the model: the generative backend, such as Claude or GPT, receives Core's instructions through its host app. The context gateway is the one part that stands between a host app and the model API, and it handles the model-side request format. Some host formats still sit in Core code (Codex configuration, Claude tool names, the Codex patch format), so today another host also needs Core changes.
- The philosophy lives only in Core: the common contract, the skills and the Core code. An adapter translates Core for one host and carries no philosophy of its own; an adapter that restates a Core rule breaks this boundary.
- The host app and the generative backend are outside Ghost-ALICE. Ghost-ALICE supplies instructions and records through hooks, and it cannot force either one. For this reason Core blocks no tool, and Ghost-ALICE's own failure never stops the user's work.
- The user stands outside the structure and supplies the objective and authority. Confirming the user's intent is where the philosophy starts.
- An add-on stands outside Core. Core knows no add-on; it leaves a Stop notice that anyone can read, and an add-on attaches its own action after that notice.
- The way the model works is part of Core's design. The way the project builds and changes Ghost-ALICE, described in the contributing guide, applies to building this structure and does not run inside it.
Architecture: structure and boundaries shows what sits where.