Appendix: .ait/config.json
The complete current RC.6 persisted Repository configuration contract, including ownership, defaults, lifecycle writers, worktree overlays, and recovery boundaries.
Audience: Developers, operators, and Repository owners
Contract and authority#
.ait/config.json is the authoritative persisted Repository configuration for RC.6. It stores Repository identity and routing, workflow defaults, remote registration, Task-worktree placement, and a small set of AIT-managed runtime hints. This page enumerates every current supported field and nested field.
Three JSON surfaces are related but are not interchangeable:
| Surface | Authority and behavior |
|---|---|
.ait/config.json | Persisted Repository-wide authority. AIT reads this file from the canonical Repository root. |
.ait-worktree.json | AIT-managed overlay in one materialized worktree. Non-null overlay values replace the corresponding root values only for that worktree's effective runtime. |
ait config show --json | Effective diagnostic projection after defaults, derivation, actor detection, remote resolution, and any worktree overlay. It is not a byte-for-byte rendering of either file. |
The JSON reader may preserve an unrecognized key while rewriting another setting. Preservation does not make that key supported. Do not use arbitrary keys as extension points.
Safe mutation boundary#
Use the command that owns a value whenever RC.6 exposes one:
ait config show --json
ait config set --workflow-mode solo_remote
ait config set --id-namespace-prefix W
ait config unset task-worktree-main-seed-ram-max-bytes
ait remote add origin https://server.example.invalid --default
ait doctor memory-root --jsonait config set admits ten user-owned settings and ait config unset admits eight optional overrides. Repository indexes, Line selectors, remote records, derived scopes, Plan binding internals, worktree overlays, and wait hints are not writable through ait config set. Let their owning AIT lifecycle write them.
If an advanced file-only value must be maintained, stop concurrent AIT mutations, preserve a trusted copy, write valid JSON atomically, and verify the result before resuming work. Never copy another Repository's repository_index, remote map, or worktree overlay.
Representative root file#
This neutral sample shows the common shape; it is not a recovery template. The server-assigned index, remote metadata, paths, and identity must come from the Repository's own lifecycle.
{
"repo_name": "sample-project",
"default_line": "main",
"current_line": "main",
"default_remote": "origin",
"repository_index": 42,
"remotes": {
"origin": {
"remote_id": 1,
"url": "https://server.example.invalid",
"repo_name": "sample-project",
"created_at": "2026-08-16T08:00:00Z"
}
},
"id_namespace_prefix": "W",
"policy_profile": "prototype",
"default_author_mode": "ai_with_human_review",
"workflow_mode": "solo_remote",
"workflow_default_scope": "remote",
"task_default_scope": "remote",
"change_default_scope": "remote",
"sprint": "on",
"plan_task_binding": { "mode": "required" },
"task_worktree": {
"alias_root": ".ait-worktree-links",
"main_seed_ram_max_bytes": 8589934592
}
}Fresh initialization#
ait init creates repo_name, default_line, current_line, a null default_remote, an empty id_namespace_prefix, policy_profile, default_author_mode, sprint, and plan_task_binding. It adds default_model only when supplied. On a supported host it can also record a detected task_worktree.memory_root.
The default Line is main. Without an explicit Repository name, the canonical root directory name is used. A fresh policy profile is one of prototype, team, or release; it must match .ait/policy.yaml.
Repository identity and Line selection#
| Field | JSON contract | Owner, absence, and mutation |
|---|---|---|
repo_name | Nonempty string. | ait init writes it. If missing in an older Repository, runtime falls back to the canonical root directory name. It is not remote identity. |
default_line | Nonempty Line-name string. | ait init writes it; absence falls back to main. Repository initialization owns changes. |
current_line | Nonempty Line-name string. | AIT Line operations maintain the selected canonical-root Line. Absence falls back to default_line. |
default_remote | Remote-name string or null. | ait remote add ... --default writes it. A non-null value must name an entry in remotes; absence means no default remote. |
repository_index | Unsigned 32-bit integer. | The server allocates it and ait remote add persists it. Once present, RC.6 refuses to replace it with a newly returned index. There is no public setter. |
id_namespace_prefix | String containing only ASCII letters or digits; stored uppercase. Empty is valid. | ait init, ait config set --id-namespace-prefix, or ait config unset id-namespace-prefix. The current server namespace is at most two characters; use the empty value or a value accepted by both client and server. |
Policy, provenance, and local reviewer defaults#
| Field | JSON contract | Owner, absence, and mutation |
|---|---|---|
policy_profile | prototype, team, or release. | Selected by ait init; it must equal the policy ID in .ait/policy.yaml. Do not change only one side. |
default_author_mode | human_only, human_with_ai_assist, ai_with_human_review, or ai_only_experimental. | ait init, ait config set, or ait config unset. Absence resolves to ai_with_human_review. |
default_model | Nonempty string when present. | Optional ait init value or ait config set; ait config unset default-model removes it. Absence is reported as null. |
user_name | Nonempty string when present. | ait config set or unset. Used as the default local display/review identity. |
user_email | Nonempty string when present. | ait config set or unset. Used in effective local actor and reviewer identity. |
task_review | Boolean: true means required; false means automatic. | ait config set --task-review required or ait config set --task-review automatic converts the word to this boolean. Absence resolves to automatic. |
The effective actor can also come from AIT_NATIVE_ACTOR. Therefore the effective values shown by ait config show --json can differ from the stored identity fields.
Workflow preset coupling#
Set the complete preset rather than editing its dependent fields separately:
workflow_mode | Stored scope values |
|---|---|
solo_local | workflow_default_scope, task_default_scope, and change_default_scope are local. |
solo_remote | workflow_default_scope, task_default_scope, and change_default_scope are remote. |
team_remote | workflow_default_scope, task_default_scope, and change_default_scope are remote. |
ait config set --workflow-mode <value> writes workflow_mode and all three scope fields. It also writes sprint: "on" and plan_task_binding.mode: "required" unless --sprint off is supplied in the same command.
| Field | JSON contract | Owner, absence, and mutation |
|---|---|---|
workflow_mode | solo_local, solo_remote, or team_remote. | ait config set --workflow-mode. If absent or inconsistent, the effective projection is derived from the scopes and Plan binding and can report custom. |
workflow_default_scope | local or remote. | Written by the workflow preset. Absence resolves to local. |
task_default_scope | local or remote. | Written by the workflow preset. Absence inherits workflow_default_scope. |
change_default_scope | local or remote. | Written by the workflow preset. Absence inherits workflow_default_scope. |
sprint | on or off. | ait init or ait config set --sprint. When present, it is the effective authority for Plan binding. |
plan_task_binding.mode | off, advisory, strict, or required. | Current public writers emit required for sprint on and off for sprint off. If sprint is absent, this object supplies the effective mode; if both are absent, RC.6 stages required. |
Changing these defaults does not relocate or rewrite an existing Task, Change, Plan binding, or worktree. Existing work finishes under the contract recorded when it started.
Remote map#
remotes is an object keyed by the local remote name. ait remote add is its public writer.
| Field | JSON contract | Owner and behavior |
|---|---|---|
remotes | Object whose keys are nonempty remote names. | Absent means no registered remotes. Each value must be an object. |
remotes.<name>.remote_id | Signed integer. | AIT assigns the next local ordinal. Older entries without it are read using their deterministic map ordinal, but current writes include it. |
remotes.<name>.url | Nonempty string. | Required server base URL supplied to ait remote add. |
remotes.<name>.repo_name | Nonempty string or absent. | AIT records the canonical Repository directory name used for server registration. |
remotes.<name>.created_at | RFC 3339 timestamp string. | AIT records registration time. Older records can omit it. |
The remote URL can reveal private network topology. It is routing data, not a credential. Authentication tokens belong in the process secret boundary, not this file.
task_worktree object and AIT_RAM#
| Field | JSON contract | Owner, absence, and mutation |
|---|---|---|
task_worktree | Object or null. | ait init can add detected memory-root data. Absence still allows host discovery and persistent-disk fallback. |
task_worktree.memory_root.kind | macos_ram_volume, linux_memory_root, or windows_ramdisk. | Must match the host and the proof expected by ait doctor memory-root --json. |
task_worktree.memory_root.root | Nonempty path string. | Memory-backed root. Operator-maintained; use an absolute path for unambiguous diagnostics and recovery. |
task_worktree.memory_root.volume_name | Nonempty string or absent. | macOS-only volume label. Other kinds ignore it. When absent on macOS, AIT can derive it from the mount basename. |
task_worktree.memory_root.sector_count | Positive integer or absent. | macOS RAM-disk capacity in 512-byte sectors. Absence uses 16,777,216 sectors, exactly 8 GiB. Other kinds ignore it. |
task_worktree.ephemeral_root | Nonempty path string or absent. | File-only Task runtime root. Relative paths resolve from the canonical Repository root. Absence derives the runtime location from a valid memory root when available. |
task_worktree.alias_root | Nonempty path string or absent. | ait config set --task-worktree-alias-root; relative paths resolve from the Repository root. Absence uses .ait-worktree-links. |
task_worktree.main_seed_ram_max_bytes | Nonnegative integer or absent. | ait config set or ait config unset task-worktree-main-seed-ram-max-bytes. Absence means no configured Snapshot-size cutoff; it does not mean unlimited physical RAM. |
Memory placement is evaluated when a new Task worktree is created. A Snapshot strictly larger than a configured main-seed limit uses Repository-internal persistent storage. Otherwise AIT uses a validated supported RAM root when it can and falls back to Repository-internal persistent storage when it cannot. The complete isolation, capacity, and recovery behavior is in Parallel Task Isolation.
workflow_quick object#
This optional advanced object narrows the local quick-modification classifier. RC.6 has no ait config set option for it.
| Field | JSON contract | Absence and behavior |
|---|---|---|
workflow_quick.max_files | Positive integer. | Invalid or absent uses 8. It caps changed file count for quick classification. |
workflow_quick.max_bytes | Positive integer. | Invalid or absent uses 65,536. It caps total changed bytes for quick classification. |
workflow_quick.forbidden_prefixes | Array of nonempty path-prefix strings. | Valid entries add Repository-specific exclusions to the built-in exclusions; they do not replace built-in safety checks. |
Always inspect the resulting decision with ait workflow tier --json. This object cannot make remote work quick and cannot bypass binary-file, special file, conflict, or protected-path checks.
AIT-managed operational fields#
| Field | JSON contract | Owner, absence, and behavior |
|---|---|---|
worktree_name | Nonempty string or absent. | AIT temporarily binds the canonical root to an active managed worktree and clears the binding during cleanup. Do not hand-edit it. |
workflow_ready_poll_seconds | Number. | AIT learns a rounded readiness wait estimate from recent remote history. Positive effective values are clamped to 5 through 900 seconds; 0 marks an attempted bootstrap with no usable sample. Absence means no cached estimate. |
workflow_land_poll_seconds | Number. | Same AIT-owned estimate for remote Land completion. It has the same 5-through-900-second effective bounds and 0 bootstrap marker. |
The wait values are hints for user feedback, not readiness, policy, or timeout authority. Removing or changing them does not make an operation complete.
Compatibility fields in existing files#
These fields can remain in an upgraded Repository. They are documented so a backup or audit is intelligible; do not add them to a fresh RC.6 file.
| Field | JSON contract | Current RC.6 meaning |
|---|---|---|
repo_id | Older opaque string. | Preserved compatibility data. Current server routing identity is repository_index; repo_id must not be used to select remote authority. |
snapshot_binary_db_storage | Existing scalar value. | The current runtime always uses Binary DB layout 1 and ignores the selector value. Omission has the same storage behavior. |
plan_binary_db_storage | Existing scalar value. | Same fixed layout-1 behavior for Plan authority. |
remote_sync_binary_db_storage | Existing scalar value. | Same fixed layout-1 behavior for remote-sync authority. |
plan_task_binding_mode | Older scalar mode. | Used only by a bounded compatibility path. Current configuration writes and reads plan_task_binding.mode; do not add the scalar to a new file. |
Complete worktree overlay#
AIT creates .ait-worktree.json in a managed worktree and merges every non-null value over the root configuration for that worktree. A Task worktree uses the following fields:
| Field | JSON contract | Meaning |
|---|---|---|
worktree_name | Nonempty string. | Stable AIT-owned materialization name and cleanup identity. |
current_line | Nonempty Line-name string. | Task feature Line selected inside this worktree. |
repo_root | Absolute path string. | Canonical Repository root whose .ait authority is shared through the managed link. |
workspace_root | Absolute path string. | Physical worktree root. It can differ from the user-facing alias path. |
created_at | RFC 3339 timestamp string. | Materialization time. |
materialized_snapshot_id | Snapshot ID string or absent. | Snapshot currently restored into the worktree; AIT updates it after restore and rebase operations. |
The overlay is ownership metadata, not a portable user profile. Do not copy or edit it, and do not replace the managed .ait link with a separate authority.
Verification, backup, and recovery#
After a supported change, verify both the effective projection and the relevant subsystem:
ait config show --json
ait remote list --json
ait status --json
ait doctor memory-root --jsonBack up the entire .ait authority, not only config.json. The file contains the server-assigned Repository index and remote routing required to reconnect the local authority to its existing offsite copy. Redact server URLs, local paths, names, and email addresses before sharing diagnostics. The file should not contain passwords, bearer tokens, or integration secrets.
If local authority is lost, do not run ait remote add against an existing duplicate-named server Repository and assume it will reattach. Restore the trusted saved repository_index, default_remote, and remotes routing data as part of the saved local authority, verify it with ait config show --json and ait repo show --remote origin --json, then preview ait remote recover-head --remote origin before adding --apply. If the exact saved routing cannot be restored, stop instead of creating replacement authority.