Configuration Registry

Every file that shapes how OGL Cortex behaves, the real shape of each record type, how a turn's context is assembled, and which file owns each kind of setting.

Placeholders ($CORTEX_HOME, $CTX_ROOT, <instance>, <org>, <seat>, <project-slug>) are defined in 01.

Why a registry

Three different readers consume configuration:

• Claude Code reads settings, CLAUDE.md files, hooks, skills, MCP config and auto-memory.
• The OGL Cortex daemon reads seat config.json, .env files, org context.json, crons.json and enabled-agents.json.
• The model reads bootstrap files because a prompt tells it to.

When one fact lives in two files, the copies drift, and a seat acts on whichever copy it reads first. This registry names one owner file for each kind of setting.

Terms:

• Seat: one agent's folder, orgs/<org>/agents/<seat>.
• Hook: a command Claude Code runs at a fixed moment (before a tool call, after compaction). It can block the action or add context.
• Compaction: Claude Code summarising the conversation when the context window fills.
• Gate: the auditor seat checking an artifact and returning PASS or FAIL.
• .gated-<sha>: a read-only frozen copy of a file at the exact version the auditor passed.
• .bak-<timestamp>-<reason>: a manual backup taken before an edit.

1. The registry

1.1 Who reads what

1.2 Registry table

Guard names used below:

• Surface guard: shared_surface_guard.py (source harness/hooks/shared_surface_guard.py, installed to <seat>/.claude/hooks/ogl/, or ~/.claude/hooks/ogl/ with --user-level), a PreToolUse hook that blocks Bash writes to shared roots. Default roots: ~/.claude, ~/.claude.json, the shared uv cache, global npm and brew upgrade, plus any root in OGL_SURFACE_EXTRA_ROOTS; writes under ~/.claude/projects/ are exempt (rules in surface.py). Seat folders are not in the default list.
• Hash watch (optional, not included): an infrastructure-seat cron that hashes every watched settings, hook, skill, CLAUDE.md and MCP file and pages the orchestrator once per change.
• Auditor gate: auditor review before a change goes live, with a .gated-<sha> copy kept.

The command-line tool is named cortextos.

1.3 Hook sets by role

Every template ships cortextos bus hook-loop-detector as a PreToolUse hook (templates/orchestrator/.claude/settings.json). Keep it unless you replace it with an equivalent.

Keep hook scripts in <seat>/.claude/hooks/ (the installer uses <seat>/.claude/hooks/ogl/) or <seat>/tools/. A hook registered from a deliverables or scratch folder disappears silently when someone cleans that folder.

1.4 Backups and frozen copies

• Take a .bak-<UTC timestamp>-<reason> copy before editing any settings or hook file by hand.
• After the auditor passes a hook or guard, copy it to <file>.gated-<sha> and chmod 400 it. The next change is then a diff against the passed version.
• With a git repo for ~/.claude/hooks and each seat, prefer commits and tags over loose .bak files.

2. Record shapes

2.1 Seat config.json

Template default (templates/orchestrator/config.json, crons omitted):

{
  "agent_name": "{{agent_name}}",
  "enabled": true,
  "runtime": "claude-code",
  "startup_delay": 0,
  "max_session_seconds": 255600,
  "max_crashes_per_day": 10,
  "working_directory": "",
  "timezone": "",
  "day_mode_start": "",
  "day_mode_end": "",
  "communication_style": "",
  "approval_rules": {"always_ask": [], "never_ask": []},
  "ecosystem": {"local_version_control": {"enabled": true}}
}

A configured orchestrator adds model and context settings:

{
  "agent_name": "boss",
  "enabled": true,
  "runtime": "claude-code",
  "startup_delay": 0,
  "max_session_seconds": 255600,
  "max_crashes_per_day": 10,
  "working_directory": "$CORTEX_HOME/orgs/<org>/agents/boss",
  "timezone": "America/New_York",
  "day_mode_start": "09:00",
  "day_mode_end": "21:00",
  "communication_style": "Terse. Lead with the answer.",
  "approval_rules": {"always_ask": ["external-comms", "financial", "deployment", "data-deletion"], "never_ask": []},
  "ecosystem": {"local_version_control": {"enabled": true}},
  "model": "<model id>",
  "profile": "<profile>",
  "ctx_warning_threshold": 80,
  "ctx_handoff_threshold": 88
}

working_directory must be an absolute path in the real file. 255600 seconds is 71 hours, the default --continue rotation. Other keys the daemon reads: dangerously_skip_permissions (default on unless false), telegram_polling, voice_id. Analyst templates add ecosystem.upstream_sync, catalog_browse and community_publish. agent-codex sets runtime: "codex-app-server"; agent-opencode sets runtime: "opencode".

2.2 goals.json

Seat file:

{
  "focus": "One sentence: what this seat works on today.",
  "goals": ["Goal one", "Goal two"],
  "bottleneck": "What blocks progress, or empty.",
  "updated_at": "2026-01-01T09:00:00Z",
  "updated_by": "boss"
}

The org file (orgs/<org>/goals.json) adds north_star, daily_focus and daily_focus_set_at.

2.3 crons.json entry

{
  "name": "morning-review",
  "prompt": "Read .claude/skills/morning-review/SKILL.md and execute the morning review workflow, including goal cascade from .claude/skills/goal-management/SKILL.md. Send at most one consolidated Telegram. Then run: cortextos bus update-cron-fire morning-review",
  "schedule": "0 8 * * *",
  "enabled": true,
  "created_at": "2026-01-01T00:00:00.000Z",
  "metadata": {"migrated_from_config": true, "original_type": "recurring"},
  "last_fired_at": "2026-01-02T08:00:05.343Z",
  "fire_count": 1,
  "last_fire_attempted_at": "2026-01-02T08:00:05.343Z"
}

Five-field expressions run on the daemon's local clock (02, section 6.2). The legacy template form in config.json uses type and cron keys; migration converts it to this shape.

2.4 settings.json hook block

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command",
                   "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/ogl/brief_guard.py"}]
      },
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [{"type": "command",
                   "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/ogl/future_time_guard.py",
                   "timeout": 5}]
      }
    ]
  },
  "statusLine": {"type": "command", "command": "cortextos bus hook-context-status", "refreshInterval": 5},
  "autoCompactWindow": 430000
}

Claude Code sets $CLAUDE_PROJECT_DIR to the seat directory when it runs a hook command. The full block the installer merges is harness/settings.example.json. The statusLine command writes context_status.json, which the daemon reads for context handoff.

2.5 Skill frontmatter

---
name: goal-management
description: "Daily goal lifecycle management. Use for: morning briefing goal cascade, setting daily focus, refreshing agent goals, reviewing goal progress."
triggers: ["goals", "daily focus", "priorities", "goal cascade"]
---

Only name and description are parsed (src/cli/list-skills.ts). triggers is a hint for the model.

2.6 Auto-memory file frontmatter

---
name: lookup-before-inference-for-owned-systems
description: "For a system whose mechanism is written in code you own, read the source before inferring."
metadata:
  node_type: memory
  type: feedback
  originSessionId: <session uuid>
  modified: 2026-01-01T00:00:00.000Z
---

type is one of feedback, project, reference, user. The index MEMORY.md carries one short line per file.

2.7 Task record

$CTX_ROOT/orgs/<org>/tasks/<task_id>.json:

{
  "id": "task_<epoch ms>_<random>",
  "title": "Scan untracked directories for credentials before auto-commit",
  "description": "TASK: ...\nFILES: ...\nBAR: ...\nRETURN: ...",
  "type": "agent", "needs_approval": false, "status": "in_progress",
  "assigned_to": "<seat>", "created_by": "<orchestrator>", "org": "<org>",
  "priority": "normal", "project": "", "kpi_key": null,
  "created_at": "2026-01-01T05:04:37Z", "updated_at": "2026-01-01T05:04:49Z",
  "completed_at": null, "due_date": null, "archived": false
}

The four TASK/FILES/BAR/RETURN lines are enforced by brief_guard.py on dispatches.

2.8 Inbox message

$CTX_ROOT/inbox/<seat>/<priority>-<epoch ms>-from-<sender>-<rand>.json, moved to inflight/ then processed/:

{
  "id": "<epoch ms>-<sender>-<rand>",
  "from": "<sender>", "to": "<seat>", "priority": "normal",
  "timestamp": "2026-01-01T05:04:49.000Z",
  "text": "ACK task_<id>. Starting now.",
  "reply_to": "<original msg id>",
  "sig": "<HMAC-SHA256, keyed by $CTX_ROOT/config/bus-signing-key>"
}

2.9 truth_correction event

Written by harness/tools/emit-truth-correction.sh. Keep one copy on PATH or call it from the repo checkout. Events land in $CTX_ROOT/orgs/<org>/analytics/events/<seat>/<date>.jsonl:

{
  "id": "<epoch>-<seat>-<rand>", "agent": "<seat>", "org": "<org>",
  "timestamp": "2026-01-01T21:58:29Z", "category": "action",
  "event": "truth_correction", "severity": "info",
  "metadata": {
    "kind": "self_correction", "caught_agent": "<seat>", "caught_by": "<seat>",
    "catcher_type": "party", "triggering_msg": null,
    "occurred_at": "2026-01-01T21:58:29Z",
    "dedupe_key": "<seat>.<slug>.<UTC stamp>",
    "claim": "Reported 69 duplicate items",
    "correction": "13 real duplicates; 56 were untitled items grouped together; corrected in the next message",
    "evidence": "<path to log or receipt>"
  }
}

The script enforces a canonical kind enum, a derived caught_by, an injective dedupe_key and no future occurred_at. One file plus symlinks is the recommended pattern for any script shared across seats.

2.10 Templates

Create a seat with cortextos add-agent <name> --template <template>. Fill IDENTITY.md after creation: cortextos bus list-agents builds the role string from it (src/bus/agents.ts). Local edits to template skills will conflict with a later template upgrade; keep a list of skills you changed.

3. Prompt assembly

3.1 Layers in order

3.2 Environment variables

The daemon sets these in every seat terminal (src/pty/agent-pty.ts):

The daemon writes these to <seat>/.cortextos-env on each start. Secret load order: org secrets.env first, then the seat .env. A key defined in both takes the seat value without warning, so define each key in one file only.

3.3 Startup prompt

buildStartupPrompt() (src/daemon/agent-process.ts) composes: current UTC time; "Read AGENTS.md and all bootstrap files"; "do NOT call CronCreate"; overdue reminders; the deliverables rule if context.json sets require_deliverables; a handoff block after a context handoff; and "Send a Telegram message to the user saying you are back online" unless telegram_polling is false. A --continue restart uses buildContinuePrompt().

3.4 Cron prompts

The scheduler injects [CRON FIRED <iso>] <name>: <prompt> (src/daemon/agent-manager.ts). A manual fire from the dashboard injects [CRON: <name>] <prompt> (src/daemon/ipc-server.ts). Hooks that special-case crons must match both prefixes.

Cron prompts can carry real logic, for example a liveness canary procedure inside the heartbeat prompt. Such logic is outside hook review and outside git unless you export it. Prefer a short prompt that points to a skill or script in the seat repo.

3.5 Hook-injected context (orchestrator reference set)

3.6 Goals cascade

1. The orchestrator reads orgs/<org>/goals.json, asks the owner for the day's focus, and writes daily_focus.
2. It writes each active seat's goals.json.
3. cortextos goals generate-md --agent <seat> --org <org> renders GOALS.md from that seat's goals.json only (src/cli/goals.ts).
4. It messages each seat.

To prove the cascade ran, the morning-review cron should check that updated_at is today on every running seat's goals.json. Write each goals.json with an atomic write (temp file plus rename).

Check scripted phrases in skills against the send guard's banned-phrase list. A skill that tells the seat to open with a stock phrase the guard bans produces a block on every run.

4. Keeping configuration consistent

4.1 One long-term memory store per seat

A seat can end up with three memory stores: the root <seat>/MEMORY.md, a <seat>/memory/MEMORY.md, and Claude Code's native auto-memory under ~/.claude/projects/<project-slug>/memory/. In-session memory writes land in the native store. Pick one store as the long-term memory, keep it under the 200-line index limit, and point the boot list at it. If you keep a second file, name it in the boot list or delete it.

Warnings that point at line numbers in another file go stale when that file is rewritten. Point at a named entry instead.

4.2 Facts that tend to drift

4.3 Retired seats

cortextos stop <seat> stops a seat but leaves its folder, state folder, heartbeat record and crons.json. Crons for a seat with no running process do not fire, but they still appear in exports. When you retire a seat for good, archive its folder and remove its state folder and crons.json.

4.4 Version control

• $CORTEX_HOME/.gitignore ignores orgs/. Give the org and each seat its own private repo, with .env*, telegram-images/ and deliverables ignored.
• Put ~/.claude/hooks, ~/.claude/settings.json and ~/.claude/CLAUDE.md in a private local repo.
• The hash watch pages on change but does not keep the old version. Git does.
• The analyst's nightly auto-commit cron snapshots seat repos locally and never pushes. Scan untracked folders for credentials before each commit.

5. One owner file per setting

6. Known limitations

1. orgs/ is outside the framework repo. Seat and org config has no history unless you add repos (4.4).
2. No config file is validated at write time. A malformed config.json or settings.json fails at the next start or the next hook run.
3. Seat .env silently overrides org secrets.env. There is no warning for a key defined twice.
4. cortextos goals generate-md reads only the seat goals.json. It does not merge the org file.
5. Template skills edited in a seat do not merge on upgrade. A template update overwrites or conflicts with local edits.
6. Manual cron fires use a different prefix. [CRON: <name>] from the dashboard versus [CRON FIRED <ts>] from the scheduler.
7. list-agents mode is self-reported. The day or night mode shown per seat comes from the seat, not from the daemon's clock.
8. Retired seats leave state behind. Stopped seats keep heartbeat records, state folders and cron files until removed.

Source files

• src/bus/crons.ts, src/bus/crons-schema.ts, src/bus/agents.ts, src/bus/system.ts
• src/types/index.ts
• src/daemon/cron-migration.ts, src/daemon/cron-scheduler.ts, src/daemon/agent-manager.ts, src/daemon/ipc-server.ts, src/daemon/agent-process.ts, src/daemon/fast-checker.ts
• src/pty/agent-pty.ts
• src/utils/env.ts
• src/cli/goals.ts, src/cli/list-skills.ts
• templates/*/config.json, templates/*/.claude/settings.json, templates/org/
• .gitignore