Directive Architecture — Inbound¶

How the operator directs Franklin¶

Status: v1 — file_edit end-to-end. The other six directive types are wired through the constitutional gates and explicitly REFUSED at admissibility with directive_type_not_yet_implemented until their executors land. The architecture is exercised for every directive type on day one.

Related pages: Franklin-Consciousness-MQ · Sovereign-M8-Qualification · MCP-Cell-Server

1. The constitutional rule¶

The operator issues directives. Franklin receives them, classifies them, reasons against substrate, executes through authorized cells, and reports outcomes back through a sealed causal chain. The operator has authority. The LLM has none. Franklin has constitutional responsibility for closure.

A directive is any operator message that demands a state change ("fix X", "rewrite Y", "add domain Z", "deploy V"). Distinguished from pure inquiry ("what is the status of X?") which is read-only and falls through to the existing chat reply path.

2. The nine actors (strict order)¶

Every directive walks this chain. Each actor writes a sealed substrate row before the next one runs. Source files live in cells/xcode/Sources/GaiaFTCLApp/.

#	Actor	Responsibility	Sealed output
1	`UserInputIngestor`	Hashes the message under canonical JSON, anchors `tauBlock`, classifies inquiry/directive/mixed	`user_directives` row
2	`DirectiveClassifier`	Identifies directive type, scope, target cells, risk, required quorum (5 default; 9 for `architectural`)	`directive_classifications` row
3	`DirectiveAdmissibilityGate`	Operator signature check, scope boundedness, banlist scan, vocabulary check, type implementation check	`directive_admissibility_receipts` row (admitted / needs-clarification / REFUSED)
4	`FranklinDirectiveOrchestrator`	Composes the execution plan from substrate state. Does not consult an LLM. For `file_edit`, parses the operator-supplied content from a fenced block.	`directive_execution_plans` row
5	`DirectiveExecutionPlanGate`	Runs the 8-axis rule-based closure (`DirectiveAxisScorers`); seals CALORIE / CURE / REFUSED	`directive_plan_receipts` row
6	`HighRiskConfirmationActor`	For high-risk directives, captures operator countersignature on the specific `plan_sha256` prefix	`directive_confirmations` row
7	`DirectiveExecutor`	Walks the plan steps. For `file_edit`: read → snapshot → write → `swift build` → `swift test`. Rolls back from the snapshot blob on any failure.	`directive_step_receipts` rows
8	`DirectiveExecutionGate`	Verifies every plan step produced a receipt; seals final state	`directive_execution_receipts` row
9	`FranklinDirectiveReporter`	Writes only what the receipts say. Goes through `franklin_responses` (forward-compatible stub for the future outbound emitter).	`franklin_responses` row

DirectivePipeline is the single entry point that walks the actors. FranklinChatState.send() calls it before falling through to the LLM chat reply path.

3. Directive types¶

Seven types defined by DirectiveType. Only file_edit is fully implemented in v1. Every other type is recognized, classified, and REFUSED at admissibility with a sealed receipt — the architecture is exercised for all seven on day one.

Type	Scope	Risk	Quorum	Status
`file_edit`	Specific path under `cells/xcode/Sources/`	medium (high for `Migration` / `Schema` / `Package.swift`)	5	Implemented
`code_generation`	New file path under bounded scope	medium	5	REFUSED (`directive_type_not_yet_implemented`)
`domain_addition`	New domain id	high	5	REFUSED
`audit_request`	Read-only scope	low	5	REFUSED
`deployment`	Specific cells	high	5	REFUSED
`substrate_mutation`	Specific substrate rows	high	5	REFUSED
`architectural`	Actor topology / gate change	highest	9	REFUSED

4. The 8-axis closure (rule-based)¶

The plan gate runs eight rule-based scorers (DirectiveAxisScorers.swift). Each axis returns a score in [0, 1]. The lowest axis sinks the plan — the terminal state is determined by min(axes) against the CALORIE (≥ 0.80) / CURE (≥ 0.55) / REFUSED thresholds.

Axis	Rule
s₁ structural	Plan has steps; indices contiguous; required_cells non-empty; rollback strategy substantive; `file_edit` plans must include `snapshotFile` before `writeFile`
s₂ temporal	Plan's `tauBlock` matches current within 6 blocks (~1 hour); 0.40 if substrate unmoored
s₃ spatial	`file_edit` / `code_generation` target paths must live inside `cells/xcode/Sources/`; absolute paths score 0.20; `..` path traversal scores 0.00
s₄ observable	Mutating plans must include both build and test verification steps; otherwise 0.20
c₁ trust	Banlist match in directive content (not in removal context) → 0.10
c₂ identity	Operator session signature present and valid; empty signature → 0.05
c₃ closure	Every step kind in the plan must be one we know how to receipt
c₄ consequence	High-risk directives without required confirmations → 0.30; `architectural` with quorum < 9 → 0.25; irreversible `file_edit` (no rollback) → 0.20

When the full dialectic engine lands, DirectiveAxisScorers is replaced. Every downstream consumer reads the same EightAxisScore struct — no migration needed.

5. The banlist¶

DirectiveBanlist (Core) maintains substrings that signal a constitutional bypass attempt:

External LLM SDK imports — import openai, import anthropic, ChatCompletion, OpenAI(, Anthropic(
Agentic framework imports — langchain, AutoGPT, AgentExecutor, ReActAgent
Unbounded outbound HTTP in sovereign code paths
Self-modifying loops — self_modify, agentic loop

A banlist hit in directive content is REFUSED unless the directive is in a removal/audit context (verbs remove, delete, audit for, find any, purge, eliminate, ban within 60 characters before the match). That preserves the architecture's ability to use these strings to evict such patterns from the codebase.

6. Substrate tables (migration v13)¶

Migration v13_directive_architecture in DirectiveSchema.swift creates ten tables and one view:

Table / View	Purpose
`user_directives`	Every directive ever received, with operator signature and `received_at_tau_block`
`directive_classifications`	Output of actor 2
`directive_admissibility_receipts`	Output of actor 3 — every REFUSED is a sealed row, audit complete
`directive_execution_plans`	Output of actor 4
`directive_plan_receipts`	Output of actor 5 — full 8-axis scores + terminal state + quorum
`directive_confirmations`	Operator countersignatures on high-risk plans
`directive_step_receipts`	One row per executed plan step
`directive_execution_receipts`	Output of actor 8 — final seal
`directive_file_snapshots`	`BLOB` storage for `file_edit` rollback. Keyed by `(directive_sha256, file_path)`. The prior file bytes, durable before any `writeFile` step runs.
`franklin_responses`	Outbound reporter sink. Forward-compatible with the future `FranklinResponseEmitter`.
VIEW `directive_causal_chains`	Joins every table above for any `directive_sha256`. Returns the full chain (`user_directive → classification → admissibility → plan → plan_receipt → confirmation → steps → execution → response`) in chronological order. The audit surface.

Every receipt has: - *_sha256 primary key (canonical-JSON SHA-256 of the receipt fields) - signed_by_cell or signed_by_user - tau_block anchor (Bitcoin block height) - timestamp_iso - causal_parent reference where applicable

All writes use INSERT OR IGNORE keyed by sha256 — receipts are immutable once written. A retry that produces the same sha256 is a no-op.

7. Issuing a directive¶

The chat surface accepts a directive in this form. FranklinChatState.send() walks the pipeline before falling through to chat reply on inquiry.

fix cells/xcode/Sources/SomePath/Some.swift

```swift
// FULL new content of the file goes here
import Foundation
// ...
```

The orchestrator parses the new content from the first triple-backtick fence. The orchestrator does not consult an LLM and does not author content. If the directive lacks a parseable replacement, the plan gate refuses on s₁ structural.

For high-risk paths (*Migration*, *Schema*, Package.swift), the plan is parked at awaitingCountersign. Operator types:

confirm <first 8 chars of plan_sha256>

The countersign is sealed into directive_confirmations and execution resumes.

8. Inspecting the chain¶

After any directive, query the sealed history:

sqlite3 ~/Library/Application\ Support/GaiaFTCL/substrate.sqlite \
  "SELECT link_kind, link_sha256, signed_by, tau_block, summary
     FROM directive_causal_chains
    WHERE directive_sha256 = 'your-64-char-sha'
    ORDER BY tau_block ASC, timestamp_iso ASC, link_kind ASC"

Or via the MCP server causal_chain tool.

9. GAMP 5 MQ evidence — `DirectiveArchitectureMQTests`¶

Ten module-qualification tests, all PASS, in cells/xcode/Tests/GAMP5/MQ/DirectiveArchitectureMQTests.swift:

Gate	Assertion
MQ-D001	Migration v13 creates all 10 tables + the `directive_causal_chains` view
MQ-D002	Banlist matches `import openai` in addition context; allows it in removal context
MQ-D003	Absolute file path on a `file_edit` step → s₃ ≤ 0.40 → REFUSED
MQ-D004	Mutating plan without build/test verification → s₄ < 0.55 → REFUSED
MQ-D005	`writeFile` without preceding `snapshotFile` → s₁ < 0.80 → not CALORIE
MQ-D006	Empty operator signature → c₂ < 0.55 → REFUSED
MQ-D007	`architectural` directive with quorum < 9 → c₄ < 0.55 → REFUSED
MQ-D008	Well-formed `file_edit` plan with valid signature seals CALORIE
MQ-D009	`DirectiveSeal.sha256` is deterministic over canonical JSON (sorted keys)
MQ-D010	`directive_causal_chains` view returns the `user_directive` link after write

Run: cd cells/xcode && swift test --filter DirectiveArchitectureMQTests.

10. What is deliberately not implemented in v1¶

The outbound mediation architecture (FranklinResponseEmitter, FranklinResponseGate, FranklinReasoningOrchestrator, LLMAdvisoryClient, LLMAdvisoryResponseGate). Today the reporter writes to franklin_responses and the chat UI reads from the same table. When the real emitter lands, no schema change is needed.
LLM advisory plumbing. file_edit does not need an LLM (the operator supplies the content). The next directive type to land it is code_generation.
Real quorum aggregation. Plan receipts record the required quorum and write quorumState as a literal N/N. When multi-cell quorum signing lands, this field is replaced with a real signature aggregation.
Six of seven directive types. Each one is recognized, classified with full scope/risk/quorum, and REFUSED at admissibility with a sealed receipt that says directive_type_not_yet_implemented. The audit chain is complete for every refusal.

11. Critical invariants¶

No LLM authorship. The orchestrator never calls an LLM to author code. Operator supplies the content; orchestrator parses it.
No external API in sovereign code paths. Banlist enforces.
No directive without an operator signature. Empty signature → REFUSED at admissibility (signature check) AND scores 0.05 on c₂ identity (defense in depth).
Every state change produces a receipt. Including REFUSALs. The substrate audit is complete.
Every file_edit write is reversible. snapshotFile runs and is durable in directive_file_snapshots BEFORE any writeFile step executes. On failure, DirectiveExecutor.rollback restores from the snapshot blob and writes a rolledBack step receipt.
Plan must seal CALORIE to execute. DirectiveExecutionPlanGate refuses to advance a plan with terminal state CURE or REFUSED.
High-risk plans require operator countersignature. Sealed into directive_confirmations, referenced by plan_sha256. Without it, the executor refuses to run.

12. Files¶

Core types & migration: cells/xcode/Sources/GaiaFTCLCore/Directive{Types,Schema,Banlist,AxisScorers,SubstrateWriter}.swift
Actors: cells/xcode/Sources/GaiaFTCLApp/{UserInputIngestor,DirectiveClassifier,DirectiveAdmissibilityGate,FranklinDirectiveOrchestrator,DirectiveExecutionPlanGate,HighRiskConfirmationActor,DirectiveExecutor,DirectiveExecutionGate,FranklinDirectiveReporter}.swift
Pipeline + chat wiring: cells/xcode/Sources/GaiaFTCLApp/{DirectivePipeline,FranklinChatView}.swift
MQ tests: cells/xcode/Tests/GAMP5/MQ/DirectiveArchitectureMQTests.swift

Federation-cosigned

This page's source is sealed in the GaiaFTCL federation manifest — page SHA-256 55fd50b69891dfb8…, manifest witness a090592e0609adc8…, signed 2026-06-02T18:58:22Z by cell gaiaftcl-mac-cell. Verify with gaiaftcl wiki sign --all and compare wiki-all-signatures.json.