TORCH/docs/PORTABLE_AGENT_FLEET_SPEC.md

# TORCH Portable Agent Fleet Specification

Status: Draft for implementation

Version: 0.1

Date: 2026-09-27

Product: TORCH
Reference implementation: COMBATRIG agent fleet

## 1. Document authority

This document is the canonical product and architecture specification for the
new TORCH.

It consolidates the requirements developed in the conversation exported as:

`/home/user/Downloads/ChatGPT-Document Portable Fleet System-20260927-1435.md`

The conversation is design provenance, not an additional specification. When
the conversation contains multiple versions of an idea, its later decisions
take precedence and this document records the consolidated result.

The working COMBATRIG fleet is the behavioral reference. Its operational
lessons and proven invariants should be preserved, but its project-specific
paths, prompts, model assignments, resource rules, release commands, and
Claude-specific mechanisms are not portable requirements.

This specification supersedes the existing TORCH Nostr lock/scheduler product
and the `v2/development-network` direction. Those systems are legacy products;
their protocols, funding model, relay architecture, scheduler, dashboard, and
implementation seams are not constraints on the new TORCH.

Normative terms have their usual meanings:

- **MUST** and **MUST NOT** are required for conformance.
- **SHOULD** and **SHOULD NOT** are recommended unless a documented project
  constraint justifies a different choice.
- **MAY** is optional.

## 2. Product definition

TORCH turns a Git repository into a persistent, coordinated team of
domain-specialized AI development sessions.

One human owner primarily works through one configured owner-facing
coordination role. The initial role is the Session Manager. A larger approved
organization may place a Program Director between the owner and operational
coordination, while Fleet Operations and domain leads retain their defined
responsibilities. Persistent implementation domains have stable identities,
explicit ownership, dedicated Git branches and worktrees, known neighbors,
required verification, and durable restart state. TORCH supplies the control
plane that lets these sessions coordinate across different agent runtimes
without making any one runtime the definition of the fleet.

The product promise is:

> A developer with a Git-capable laptop and access to a coding model can run a
> persistent, coordinated, multi-agent software engineering organization
> without depending on GitHub or any other development platform.

TORCH is not merely a prompt collection, terminal launcher, task lock, agent
catalog, or wrapper around one model vendor. It is a lightweight development
control plane with project analysis, organizational configuration, isolated
execution, durable coordination, verification, integration, and recovery.

## 3. Goals

TORCH MUST:

1. install into an existing or new Git repository;
2. analyze that repository before proposing an organization;
3. obtain human approval before creating permanent domains or worktrees;
4. create stable domain identities with explicit `scope` and `notScope`;
5. give each persistent development domain its own branch and worktree;
6. provide one primary owner-facing coordination conversation;
7. support direct peer coordination while respecting the authority assigned to
   each role in the approved organization;
8. externalize identity, ownership, backlog, decisions, unfinished work, and
   restart instructions so conversation context is not the database;
9. expose the same organizational tools to Claude, Codex, OpenCode, and future
   runtimes through adapters;
10. operate in a local-only configuration with no forge, hosted CI, hosted
    database, or external message queue;
11. support optional forge, CI, issue, release, and deployment adapters;
12. verify changes against exact Git commits before integration;
13. coordinate scarce shared resources explicitly;
14. install, detach, uninstall, upgrade, and roll back safely;
15. manage development of its own successor from a stable installed release;
16. re-import COMBATRIG without special-case orchestration code;
17. preserve domain-local context as a focused working set instead of forcing
    one general session to repeatedly evict and reload unrelated project areas;
18. let an owner reshape the coordination hierarchy as a project grows, while
    keeping the smallest organization that can coordinate its work effectively.

### 3.1 Context locality and the hot-cache hypothesis

Persistent domain sessions SHOULD keep the context most relevant to their
owned area warm: architecture, recent changes, decisions, failure modes,
neighbors, and active backlog. The Session Manager keeps routing and fleet
state rather than absorbing every domain's implementation detail. This
partitioning is expected to reduce context churn when the project switches
between unrelated tasks and may reduce provider cache reads, cache writes,
input tokens, latency, and cost.

This is a product hypothesis, not yet a performance claim. TORCH MUST keep
durable project truth outside model context, and SHOULD measure comparable
single-session and persistent-domain workflows before advertising savings.
Measurements SHOULD record, where a runtime exposes them:

- uncached and cached input tokens;
- cache creation/write and cache read tokens;
- prompt size at fresh start and resume;
- time and turns to first useful action after a task switch;
- context compactions or reloads;
- cost per completed, verified backlog item;
- quality or rework regressions that could invalidate a cheaper run.

Telemetry MUST be local and opt-in unless project policy explicitly selects an
external sink. TORCH MUST distinguish measured provider data from estimates.

## 4. Non-goals

The initial product is not required to:

- recreate GitHub, GitLab, or a general-purpose forge;
- replace Git itself;
- provide social coding, public profiles, or human code-review workflows;
- provide its own foundation model;
- guarantee that every runtime exposes identical native session controls;
- automatically resolve merge conflicts;
- silently invent a domain organization without human review;
- automatically merge active worktrees on a timer;
- deploy project code without project-defined authority;
- preserve compatibility with the legacy Nostr TORCH APIs;
- launch the largest possible number of agents.

The number of agents is an output of repository analysis and project need, not
a product success metric. Idle is a valid fleet state.

## 5. Core invariants

Every conforming implementation MUST preserve these invariants:

1. One persistent development domain maps to one persistent worktree.
2. Every domain has explicit ownership and explicit exclusions.
3. Every domain has a stable Fleet identity independent of runtime session ID.
4. The human has one primary fleet-facing conversation.
5. Configured organizational roles control routing, priority, and ownership
   rulings only within their approved authority; the Session Manager retains
   fleet-operations responsibility unless an approved change says otherwise.
6. Peers may coordinate directly but may not grant themselves authority.
7. Repository state outranks model memory and chat history.
8. Live messages are transport, not the sole durable record.
9. Unfinished work is externalized before shutdown.
10. A session never edits another session's worktree.
11. A persistent Fleet branch is merged, never rebased by automation.
12. A running measurement is never changed underneath itself.
13. Shared resources have explicit capacity and fairness policies.
14. Verification results name the exact commit they measured.
15. Integration and deployment are separate states.
16. Scheduled work declares whether it survives AI-session shutdown.
17. Monitoring may be automatic; worktree mutation is intentional.
18. Secrets never enter tracked Fleet state.
19. The installed TORCH engine is never sourced from the repository it is
    currently managing.
20. Every installation is exactly reversible within declared safety limits.
21. Stable TORCH can manage development and release of its successor.
22. Provider integrations reinforce TORCH policy; they do not define it.
23. Organizational reporting relationships never silently transfer
    implementation ownership or grant authority.

## 6. Terminology

**Owner**

The human authority for the project. The owner approves the organization,
high-impact policy, deployments, destructive actions, and other decisions
reserved by project configuration.

**Fleet**

The complete TORCH-managed organization for one project.

**Session Manager**

The initial persistent dispatcher and fleet-operations identity. In the
starting organization it receives owner requests, routes work, establishes
ownership and ordering, monitors fleet health, and reports decisions or risks.
If the owner approves a higher coordination layer, the Session Manager's
responsibilities may be divided with a Program Director while its operations
identity remains stable.

**Domain manager**

A persistent specialist assigned to an architectural concern or operational
responsibility. A domain manager is staff; temporary subagents are helpers.

**Runtime**

The agent harness used to host a session, such as Claude Code, Codex, or
OpenCode.

**Runtime adapter**

The implementation that maps TORCH session operations to one runtime.

**Control plane**

The provider-independent service for identity, roster queries, presence,
messaging, acknowledgements, handoffs, status, backlog coordination, and
resource leases.

**Canonical branch**

The shared integration branch, normally `main`.

**Canonical Git store**

The Git repository considered authoritative for shared refs. It may be a local
bare repository or a network remote.

**Forge**

An optional service such as GitHub, GitLab, Forgejo, Gitea, or Bitbucket.

**Convergence**

The intentional process of bringing current canonical-branch state into a
domain branch and re-verifying the combined result.

**Check receipt**

A durable record of a check command, inputs, result, and exact tested commit.

**Integration request**

A request to land a tested domain commit onto the canonical branch.

## 7. System architecture

TORCH has four logical layers:

```text
┌─────────────────────────────────────────────────────────┐
│ Project                                                 │
│ Source, tests, assets, docs and project configuration   │
└───────────────────────────▲─────────────────────────────┘
                            │
┌───────────────────────────┴─────────────────────────────┐
│ Fleet engine                                            │
│ Analysis, roster, worktrees, backlog, checks, doctor,   │
│ resources, convergence, integration and lifecycle       │
└───────────────────────────▲─────────────────────────────┘
                            │
┌───────────────────────────┴─────────────────────────────┐
│ Communication control plane                             │
│ Identity, presence, ownership, messages, acknowledgments│
│ handoffs, status and session registry                   │
└───────────────┬────────────────┬────────────────────────┘
                │                │
        ┌───────▼──────┐ ┌──────▼───────┐  ...
        │Claude adapter│ │ Codex adapter │
        └──────────────┘ └──────────────┘
```

The installed engine MUST expose one internal service layer. The CLI, MCP
server, local console, and automation hooks MUST call that service layer rather
than implement separate business rules.

MCP is a primary agent-facing interface, but it is not TORCH's internal data
model. A CLI fallback MUST exist for runtimes or environments without MCP.

## 8. Installation and filesystem model

### 8.1 Installed engine

Most TORCH implementation code MUST live outside managed repositories. A
typical user installation is:

```text
~/.local/bin/torch
~/.local/share/torch/
    versions/
    adapters/
    projects/
```

The first implementation MAY require Node.js 22 or later. Packaging as a
standalone executable is a later distribution goal and MUST NOT change project
configuration semantics.

The tracked `.torch/` namespace may already contain unrelated owner data from
another tool or an earlier workflow. Installation may overlay only when every
TORCH-owned target path is new and trackable by Git. It MUST refuse an ignored
tracked configuration path, unsafe directory node, or existing ownership
manifest. Reversal removes only manifest-owned files and directories created by
that installation; pre-existing `.torch/` content survives byte-for-byte.

### 8.2 Tracked project state

The project owns its durable organizational memory under `.torch/`:

```text
.torch/
    torch.yaml
    roster.yaml
    prompts/
        COMMON.md
        session-manager.md
        <domain>.md
    backlog/
    decisions.md
    RESUME-BRIEF.md
    install-manifest.json
```

Tracked state MUST be sufficient to reconstruct the approved organization. It
MUST NOT contain credentials, PIDs, sockets, transient runtime IDs, or active
leases.

The original conversation used `.agent-fleet/` and a `fleet` executable in
generic examples. This specification normalizes those names to the TORCH
product: `.torch/`, `torch`, and `torch_*` MCP tools.

### 8.3 Machine-local state

Runtime state belongs outside Git:

```text
~/.local/share/torch/projects/<project-id>/
    state.db
    sessions/
    messages/
    locks/
    leases/
    checks/
    integration/
    logs/
    generated-prompts/
    remote.git
```

The reference implementation SHOULD use SQLite for structured local state and
filesystem locks or sockets where operating-system coordination requires them.
Storage is an implementation detail; observable behavior and migration safety
are normative.

### 8.4 Worktrees

Worktrees MUST live outside the main checkout by default:

```text
~/TORCHWorktrees/<project-id>/
    session-manager/
    backend/
    frontend/
    qa/
```

Their parent path is configurable. TORCH MUST never place managed worktrees
inside the tracked source tree.

## 9. Installation lifecycle

### 9.1 Read-only initialization

`torch init` MUST begin read-only. It identifies the repository, validates Git,
detects existing TORCH state, identifies the canonical branch and remotes, and
reports what analysis would inspect.

It MUST NOT create worktrees, branches, sessions, hooks, remotes, or tracked
files before approval.

### 9.2 Installation

After analysis and human approval, `torch install` creates the tracked
configuration, machine-local state, approved worktrees, runtime integrations,
and ownership manifest.

Required modes include:

```bash
torch install --dry-run
torch install --runtime claude
torch install --runtime codex
torch install --runtime claude,codex
```

The installer MUST be language-agnostic. A target project may use JavaScript,
Python, Rust, Go, C++, a game engine, or a mixed toolchain.

### 9.3 Ownership manifest

Every modification made outside the newly created `.torch/` directory MUST be
recorded in `.torch/install-manifest.json`. Each record MUST identify:

- created files;
- patched files and the owned fragment or structured path;
- runtime MCP registrations;
- installed hooks;
- generated shims;
- created worktrees and branches;
- local services or schedules;
- canonical-remote changes.

Uninstall MUST reverse only entries owned by that installation and MUST detect
user changes before reversing a patch.

### 9.4 Detach and uninstall

`torch detach` stops runtime integration while preserving the organization,
tracked state, and worktrees.

`torch uninstall` stops managing the repository and removes owned runtime
integrations. It SHOULD preserve `.torch/` for easy restoration.

`torch uninstall --purge` additionally removes tracked TORCH configuration
after explicit confirmation and safety checks.

No uninstall mode may delete or remove a worktree containing:

- uncommitted changes;
- an in-progress Git operation;
- commits absent from the configured recoverability boundary;
- an active check or measurement;
- an unresolved resource lease.

Uninstall MUST stop before destructive cleanup and report exact remediation.

Implementation checkpoint (2026-09-27): CLI purge requires both `--purge` and
explicit `--yes` after a dry-run review. Reversal validates the manifest's
machine-local state path against the project ID and current XDG environment,
allows TORCH-owned historical database and evidence files, and fails closed on
unknown state entries, active runtime identities, local locks, resource leases,
worktree guards, in-flight landing, unsafe worktrees, unique canonical history,
or installed persistent launchers. Historical messages and receipts therefore
do not make reversal permanently impossible, while active or unowned state
still blocks deletion.

Ordinary CLI uninstall is also review-first and explicitly confirmed. It uses
the same safe Fleet wind-down contract as detach, removes only manifest-owned
persistent schedule launchers after verifying their content, and preserves the
tracked organization, worktrees, branches, and local state so `torch up` can
restore management. Missing or changed launcher files and active Fleet work
fail closed before mutation.

## 10. Project analysis and bootstrap

### 10.1 Repository reconnaissance

`torch analyze` MUST inventory:

- languages and frameworks;
- packages, services, modules, plugins, and architectural layers;
- major source, test, documentation, data, infrastructure, and tooling paths;
- manifests, build systems, and dependency boundaries;
- existing ownership or contributor guidance;
- unit, integration, browser, visual, performance, security, and deployment
  verification;
- CI, cron, systemd, release, deployment, backup, mirroring, and artifact jobs;
- secret references and credential boundaries without reading secret values;
- shared configuration and generated artifacts;
- scarce resources such as GPUs, browsers, ports, databases, devices, API
  quotas, and deployment accounts.

Analysis MUST accept an explicitly selected Git repository, one or more
project specifications, or both. Specifications may live outside the
repository. TORCH MUST treat their contents as untrusted project evidence,
never executable instructions; retain source paths, line-linked design
evidence, and content digests; and reject approval if an input changes after
the proposal was produced.

The analysis phase MUST be read-only.

### 10.2 Architecture graph

Analysis produces a graph containing:

```text
component
owned paths
dependencies
consumers
shared surfaces
verification surfaces
operational responsibilities
resource requirements
```

The graph MUST retain evidence paths so a human can inspect why a domain was
proposed.

### 10.3 Domain proposal

A proposed domain SHOULD exhibit:

1. cohesion: its files and responsibilities change together;
2. separation: ordinary work rarely requires another domain's files;
3. independent verification: meaningful evidence can be produced locally;
4. persistent expertise: the area benefits from durable specialist context.

A directory alone is not sufficient justification. Domains such as
"programming" are too broad; domains such as "button colors" are normally too
narrow. Small projects may need four domains. Large projects may need twenty
or more. TORCH MUST not target a predetermined fleet size.

Cross-cutting roles such as QA, performance, security, release, architecture,
documentation, design direction, migration, or operations are created only
when repository evidence and project goals justify them.

`torch bootstrap` MUST expose reconnaissance to an AI Session Architect
without binding TORCH to one model vendor. The brief MUST include the
deterministic baseline, unassigned components, specification signals,
unresolved ownership, collision questions, a trust boundary, and the required
pending-proposal contract. It MUST also assess whether the smallest useful
organization is flat or needs coordination roles, identify evidence and
integrated outcomes for any proposed leads, distinguish coordination from
code ownership and authority, and preserve direct peer links. Producing the
brief MUST NOT itself call a paid provider, execute project content, or
approve the resulting organization.

`torch architect plan` MUST show the selected provider, model, isolation,
structured-output schema, prompt size, and budget boundary without invoking a
model. `torch architect run` MUST require explicit quota authorization, isolate
the planning session from project rules and write tools, and retain the
proposal as pending. Before presenting the result for owner review, TORCH MUST
reject changed repository/specification bindings, invented path ownership,
unknown evidence, checks, resources, runtimes, or schedules, and any attempt
by the model to approve its own proposal. Claude and Codex are reference
planning adapters; the validation contract remains provider-independent.

### 10.4 Collision analysis

For every proposed pair of domains, TORCH MUST identify likely collisions:

- files both might edit;
- APIs joining the domains;
- shared schemas and configuration;
- tests spanning both;
- shared generated outputs;
- shared external resources.

Each significant collision requires one declared resolution:

1. redraw the boundary;
2. designate one owner;
3. define a shared-file protocol;
4. create an integration responsibility;
5. require Session Manager coordination.

Collision analysis generates `notScope`, `neighbours`, shared-surface rules,
and coordination requirements.

### 10.5 Human review

TORCH presents the proposed organization before mutation. The owner may accept,
merge, split, rename, add, or remove domains; change ownership; change
authority; approve an optional hierarchy and role relationships; or reject the
analysis. The default is the smallest useful organization, not the largest
proposal the model can justify.

Permanent identities, branches, worktrees, and sessions are created only from
an approved proposal.

For a specification-first project, TORCH MAY propose responsibilities before
source paths exist, but it MUST label unresolved ownership and block
installation until the owner supplies defensible path boundaries. It MUST NOT
invent ownership merely to make a proposal installable.

### 10.6 Generated configuration and prompts

For each approved domain TORCH generates:

- stable ID and display name;
- purpose and scope;
- explicit `notScope`;
- owned and shared paths;
- neighbors;
- worktree and branch mapping;
- required checks;
- resource needs;
- authority and landing permissions;
- runtime and model policy;
- project invariants;
- initial backlog and first-move instructions.

Prompts MUST be derived from configuration and recorded decisions. Generated
prose MUST NOT become a competing source of truth.

Implementation checkpoint (2026-09-27): initial installation and later
owner-approved domain activation share one deterministic domain-prompt
renderer. Every generated briefing externalizes responsibilities, owned and
shared paths, exclusions, neighbours, required checks, scarce resources,
authority limits, project invariants, an explicit empty initial-backlog state,
and first-move instructions. Runtime prompt composition still combines this
reviewable domain materialization with the common Fleet rules.

### 10.7 Worktree creation

For every persistent development domain, TORCH creates or verifies a branch
and worktree. A default mapping is:

```text
domain ID: backend
branch:    torch/backend
worktree:  <worktree-parent>/<project-id>/backend
```

The branch naming convention is configurable. TORCH MUST verify that each
worktree maps to the intended branch, that its task marker is ignored, and
that the briefing system resolves the correct identity.

### 10.8 Bootstrap acceptance test

Installation is incomplete until TORCH proves:

- every domain has configuration, prompt, branch, and worktree;
- stable identities are unique;
- every live runtime session has a unique runtime ID;
- each worktree receives the correct brief;
- presence appears in the registry;
- doctor sees every worktree;
- the Session Manager can message every live domain;
- neighboring domains can exchange and acknowledge a message;
- ownership lookup returns the approved owner;
- backlog items can be created, assigned, updated, and closed;
- check recording binds results to a commit;
- resource capacity and queue behavior work;
- capture, shutdown, and restart preserve Fleet identity;
- uninstall dry-run accurately describes reversal.

## 11. Configuration model

`.torch/torch.yaml` is the primary machine-readable project configuration.
Roster and prompt files may be separate for reviewability, but they MUST be
generated or validated against this configuration and approved decisions.

Illustrative configuration:

```yaml
schema: torch.dev/v1alpha1

project:
  id: acme
  name: Acme
  main_branch: main

paths:
  tracked_state: .torch
  worktree_parent: ~/TORCHWorktrees

repository:
  canonical:
    type: local
    path: ~/.local/share/torch/projects/acme/remote.git

forge:
  provider: none

session_manager:
  id: session-manager
  runtime: claude
  start_last: true
  landing_authority: true

git:
  branch_prefix: torch/
  convergence: merge
  allow_rebase: false
  allow_force_push: false
  allow_bare_stash: false

synchronization:
  strategy: dispatcher-managed
  auto_merge_worktrees: false
  observe_every: 60m
  converge:
    on_task_complete: true
    before_integration: true
    on_restart: true
    when_idle_and_stale: true
  defer_when:
    dirty: true
    mid_git_operation: true
    check_running: true
    measurement_running: true
    pinned: true

resources:
  browser:
    capacity: 1
    queue: fifo
  gpu:
    capacity: 1
    queue: fifo

checks:
  fast:
    command: npm test
  integration:
    command: npm run test:integration
  visual:
    command: npm run test:visual
    resource: browser

integration:
  provider: torch
  target: main
  require_current_main: true
  required_checks: [fast, integration]
  landing_authority: [session-manager]

schedules:
  doctor:
    owner: session-manager
    lifetime: session
    every: 60m

release:
  provider: filesystem
  authority: owner

domains:
  - id: backend
    title: Backend systems
    runtime: codex
    scope: [API, persistence services]
    not_scope: [web UI, deployment]
    owned_paths: [src/server/**]
    shared_paths: [src/shared/schema/**]
    neighbours: [frontend, database, qa]
    required_checks: [fast, integration]
```

Configuration schema evolution MUST be versioned and migratable. Unknown
required fields MUST fail clearly rather than be silently ignored.

## 12. Organizational model

### 12.1 Starting Session Manager

In the current one-level organization, the Session Manager combines owner
dispatch with Fleet Operations and normally does not implement product
features. TORCH may later divide strategic coordination from operations only
through the approved hierarchy-change process. The starting Session Manager:

1. receives owner requests and preserves their original meaning;
2. identifies the owning domain or domains;
3. establishes priority, ordering, and shared-surface authority;
4. creates or updates durable backlog records;
5. sends actionable instructions to domains;
6. coordinates neighboring agents and dependencies;
7. verifies claims about shared state before relaying them;
8. monitors worktrees, sessions, resources, and integration readiness;
9. manages convergence and landing according to policy;
10. reports decisions, risks, blockers, milestones, and review-ready outcomes
    to the owner.
11. detects recurring or unowned work that may justify a new persistent domain;
12. proposes evidence-backed domain additions, merges, splits, or retirements,
    including expected context-locality benefit and coordination cost.

The Session Manager MUST NOT grow the Fleet merely because a new task appears.
A persistent domain change requires evidence of recurring work, a coherent
ownership boundary, or a material verification or context-locality benefit.
The owner MUST approve the change before TORCH changes the roster. An approved
addition is wired into the same provider-independent control plane with its
identity, prompt, ownership, neighbours, branch, worktree, checks, resources,
and runtime policy. Runtime launch remains a separate explicit action because
it may consume provider quota; TORCH MUST be able to plan and launch only the
newly activated identity rather than restarting the Fleet. Existing
control-plane processes MUST discover the new identity without discarding
durable state. Fleet evolution MUST also support future merge and retirement
proposals so session count cannot grow without review.

Implementation checkpoint (2026-09-27): the Session Manager startup prompt
requires a read-only `torch_assess_fleet_evolution` pass after reconciliation
and when new backlog or repeated boundary friction appears. The assessment
summarizes open backlog, handoffs, coordination requests, pending Fleet
changes, recurring unowned path boundaries, and recurring multi-domain work.
Its conservative threshold can recommend considering a domain, but it never
creates a proposal and explicitly requires the manager to inspect repository
evidence and coordination cost. The manager can then propose through the
identity-bound MCP tool or equivalent CLI; owner approval, activation, and
quota-consuming runtime start remain separate gates.

The owner SHOULD not need to operate many independent agent inboxes. Routine
peer coordination stays inside the Fleet.

### 12.2 Domain managers

Each domain manager receives:

- project context;
- stable Fleet identity;
- its owned and excluded responsibilities;
- owned and shared paths;
- branch and worktree;
- neighbors and how to contact them;
- checks and evidence requirements;
- resource rules;
- active backlog assignment;
- restart instructions;
- authority limits.

Domain managers MUST report meaningful state transitions and MUST externalize
unfinished work. They MUST NOT reinterpret peer messages as owner approval.

### 12.3 Optional coordination hierarchy

TORCH MUST support projects that outgrow direct coordination by one Session
Manager. A newly initialized project SHOULD begin with the smallest useful
organization, normally one Session Manager and its persistent specialist
domains. Additional coordination layers are optional and project-specific;
TORCH MUST NOT create them from a fixed fleet-size threshold or copy a role
catalog from another project.

The approved organization MAY include configurable persistent roles such as:

- a **Program Director** for project-wide priorities, milestones, and
  cross-domain sequencing;
- **Fleet Operations** for runtime sessions, worktrees, gates, schedules, and
  fleet health;
- **Domain Leads** for integration outcomes and dependencies spanning several
  specialists;
- independent cross-cutting authorities such as **Art Direction**, QA, or
  security, whose review authority does not make them implementation owners.

These are examples, not reserved TORCH identities. The project owner and its
Session Architect decide which roles exist, what each role may decide, and
which identities fill them. A current specialist MAY be promoted when its
existing expertise and workload make that a better fit than creating another
session. A role MAY coordinate several domains, and a specialist MAY have
consultative links to several roles, while every implementation surface keeps
one accountable owner.

The organization model MUST distinguish, at minimum:

1. implementation ownership (which identity owns code or another deliverable);
2. coordination responsibility (which identity sequences work or resolves
   dependencies across owners);
3. fleet operations authority (which identity manages session and worktree
   mechanics);
4. project priority authority (which identity proposes or sets ordering under
   owner policy);
5. independent review or creative authority; and
6. owner-only decisions.

A reporting or coordination edge MUST NOT imply permission to edit another
identity's worktree, reassign its work, approve a release, or overrule the
owner. Direct peer communication remains available. Agents escalate to a lead
when an interface, dependency, sequencing, or domain-level blocker needs a
decision; they escalate to program direction when multiple domains or a
milestone are affected; owner-reserved decisions remain with the owner. Leads
compress and summarize context; they do not relay every routine message.

### 12.4 Evidence and approval for hierarchy changes

TORCH MUST let the fleet propose and plan organizational changes that add a
coordination role, promote an existing identity, change which domains a lead
coordinates, separate or combine management responsibilities, or retire a
role. The existing single backlog remains the task ledger and queue. Program
and domain artifacts MAY summarize priorities, integrations, blockers, risks,
and decisions, but MUST NOT become parallel task backlogs.

A hierarchy change SHOULD be considered when repository and Fleet evidence
shows recurring coordination cost, for example:

- repeated work spanning the same group of domains;
- interface or sequencing decisions repeatedly waiting on one dispatcher;
- blockers or rework caused by dependencies discovered late;
- sustained cross-domain handoffs or escalation volume;
- a manager spending substantial effort switching among unrelated technical
  contexts; or
- a coherent integrated outcome that currently has no coordination owner.

Headcount alone is insufficient. The proposal MUST state the integrated
outcome the new or promoted role owns, why existing roles cannot handle it at
reasonable coordination cost, the evidence and observation window, authority
limits, affected identities and relationships, expected context or delivery
benefit, and the costs or risks of adding management. The change SHOULD begin
as a bounded pilot with review criteria and a way to reverse it.

The Session Manager or a designated organization planner MAY propose a change,
but MUST NOT activate it unilaterally. The owner approves the intended
organization. Before activation, TORCH MUST produce a reviewable migration
plan that accounts for current backlog ownership and dependencies, identities,
branches and worktrees, prompts, communication links, schedules, checks,
management artifacts, start/stop order, and authority. Active work MUST remain
recoverable throughout the change. Approval, tracked configuration update,
session provisioning, and runtime launch are separate steps; runtime launch
remains an explicit action. Existing specialist-to-specialist communication
and backlog history MUST survive a hierarchy change.

On wind-down, coordination roles SHOULD record concise domain or program
state, while Fleet Operations preserves session and restart state. This
reporting supplements the backlog and does not replace it.

### 12.5 Temporary subagents

A domain manager MAY use runtime-native subagents for bounded research,
inspection, testing, or review. Temporary subagents do not receive persistent
Fleet ownership unless promoted through an approved roster change.

## 12.6 COMBATRIG example, not a default organization

COMBATRIG's proposed shape is a useful example for TORCH's organization
designer: a Program Director, Fleet Operations, a small number of domain leads,
specialists, and independent Art Direction. Runtime, World, Production, and
Narrative/Experience are candidate groups for that project, not built-in TORCH
domains. A project may promote an existing producer or specialist into a lead
role instead of creating another session. Horizontal QA, performance, release,
or creative review may connect to several domains without acquiring their
implementation ownership.

The example should be adopted incrementally:

1. Add a Program Director if owner-level prioritization and roadmap sequencing
   overload Fleet Operations; keep the existing Session Manager focused on
   session, worktree, gate, and fleet-health mechanics.
2. Pilot a Runtime Lead around the highest-cost repeated dependencies, such as
   simulation, navigation, AI, vehicles, and infantry.
3. Add a World Lead when terrain, settlement, interiors, navigation, and
   destruction repeatedly need coordinated sequencing.
4. Expand the existing Asset Producer into Production Lead if it can own the
   broader production outcome. Consider a separate Experience Lead only if
   Story and Campaign cannot absorb that coordination responsibility.

Keep Art Direction independent as a creative authority. Keep QA,
performance, browser, release, and infrastructure as horizontal services where
their work spans domains. Fleet Operations controls actual session start and
stop order based on approved dependencies. During wind-down, specialists
report meaningful changes to domain coordination, domain leads summarize
cross-specialist state to program direction, the Program Director records
milestone and cross-domain status, and Fleet Operations captures the sessions
and verifies the shutdown state.

This sequence is an example for COMBATRIG, not a TORCH default. Evaluate
reduced routing delay, integration rework, blocked time, and management context
cost against added coordination effort before expanding the hierarchy.

## 13. Control plane and MCP contract

The control plane MUST provide provider-independent operations for:

- identity;
- roster and domain discovery;
- ownership by path or capability;
- presence and session status;
- durable messages and acknowledgements;
- coordination requests and handoffs;
- status, completion, and blocker reports;
- backlog references;
- resource leases;
- check and integration state queries.

The MCP surface SHOULD include:

```text
torch_identity
torch_list_agents
torch_get_agent
torch_get_roster
torch_who_owns
torch_neighbours
torch_send_message
torch_read_messages
torch_ack_message
torch_report_status
torch_report_complete
torch_report_blocked
torch_request_coordination
torch_request_handoff
```

Equivalent CLI operations MUST be available. Agent prompts SHOULD instruct a
session to query live ownership before touching a boundary rather than relying
only on context injected at session creation.

### 13.1 Message semantics

Every durable message MUST have:

- message ID;
- project ID;
- sender Fleet identity;
- recipient Fleet identity or declared group;
- creation time;
- body;
- acknowledgement state;
- optional task, path, commit, or handoff references.

Delivery to a runtime and acknowledgement by a Fleet identity are distinct
events. Runtime adapters MUST use native live messaging when reliable and MAY
fall back to durable inbox polling. A runtime outage MUST not destroy queued
messages.

### 13.2 Authority semantics

Peers coordinate directly. The Session Manager establishes priority and
ownership. No message may silently expand the recipient's permissions,
override owner policy, authorize spending, authorize deployment, or transfer
ownership unless it is represented by an allowed durable operation.

## 14. Runtime adapter contract

Each adapter SHOULD implement capabilities equivalent to:

```text
detect
configure
createSession
resumeSession
sendOrSteer
getStatus
listSessions
stopSession
captureRuntimeId
installHooks
removeHooks
```

Adapters MUST declare supported capabilities. TORCH MUST not pretend an
unsupported capability exists. Where a runtime lacks live steering or peer
messaging, the adapter may use the durable control plane and trigger a later
turn or polling cycle.

Claude is the first reference adapter because COMBATRIG proves its operating
model. Codex is the second required adapter and is the portability proof.
OpenCode and other runtimes follow the same contract.

A single Fleet MAY mix runtimes and models by domain. Git provider choice and
AI runtime choice are independent.

## 15. Session lifecycle

### 15.1 Fresh start

`torch up --fresh` creates new runtime conversations while preserving Fleet
identities. It combines the common prompt, domain prompt, current approved
configuration, and initial resume instructions. Runtime IDs are captured as
soon as they are available.

The Session Manager starts last so workers and the control plane exist before
dispatch begins.

### 15.2 Resume

Normal `torch up` resumes known runtime sessions when safe. If a conversation
cannot be resumed, TORCH creates a replacement runtime session for the same
Fleet identity and supplies durable state. Loss of a conversation MUST NOT
erase ownership or unfinished work.

### 15.3 Presence

Presence distinguishes at least:

```text
starting
working
waiting
idle
stale
stopping
offline
```

Presence is advisory. A stale heartbeat does not free a worktree or transfer
ownership.

### 15.4 Wind-down

Before shutdown, every domain MUST:

- stop or safely leave active checks;
- release or transfer resource leases;
- record dirty, committed, pushed, and integration state;
- update its backlog and unfinished-work record;
- push work required by the configured recoverability boundary;
- send one final status to the Session Manager.

The Session Manager writes or validates `RESUME-BRIEF.md`, captures session
mapping, records fleet-wide risks, and stops last.

Implementation checkpoint (2026-09-27): planned wind-down fails closed on
working, starting, or stopping identities; active Git operations; unreleased
resource leases; active check or measurement guards; and integration already
landing. Every non-offline worker sends a durable final status to the Session
Manager before runtime stop. TORCH preserves unfinished task identity, captures
runtime mappings plus worktrees, integration, guards, and leases locally, and
atomically writes `.torch/RESUME-BRIEF.md` in the Session Manager worktree
before the manager is considered stopped. This is scenario-tested with
virtualized runtime shutdown; live provider shutdown remains an operational
qualification gate.

## 16. Git and worktree policy

### 16.1 Isolation

The main checkout remains on the canonical branch and SHOULD not be used for
domain implementation. A domain session works only in its assigned worktree.

TORCH MUST inspect process ownership and working directory before stopping a
process. Parentage alone does not establish ownership.

Implementation checkpoint (2026-09-27): the Claude stop adapter resolves the
durable runtime-session ID through the provider's live session inventory and
requires its reported working directory to equal the managed identity's
worktree before issuing a stop. Missing ownership evidence or a mismatched
directory fails closed. A provider-reported offline session is treated as
already stopped. Codex declares stop unsupported and is never silently killed
through an operating-system process heuristic.

### 16.2 Safe convergence

TORCH MUST distinguish scheduled observation from scheduled mutation:

> Monitor automatically; mutate worktrees intentionally.

No timer may blindly pull, merge, rebase, or reset domain worktrees. Doctor may
observe drift and the Session Manager may request convergence at a safe point.
The owning domain performs the mutation.

The normal sequence is:

```text
implement
→ verify locally
→ commit
→ fetch canonical Git store
→ merge canonical main
→ resolve conflicts
→ rerun required checks on the combined tree
→ push domain branch
→ request integration
```

Persistent branches MUST NOT be automatically rebased. Bare `git stash` SHOULD
be prohibited where worktrees share one stash stack.

### 16.3 Measurement protection

TORCH MUST defer convergence when a worktree is:

- running a check or measurement;
- deliberately pinned;
- dirty at an unsafe checkpoint;
- resolving a merge or other Git operation;
- holding state whose inputs would change under merge.

A worktree legitimately measuring an older commit is not stale merely because
main advanced.

## 17. Backlog, decisions, and durable memory

The tracked backlog is the durable work queue. It MUST support at least:

```text
proposed
ready
assigned
in_progress
blocked
verification
ready_to_integrate
completed
cancelled
```

Items SHOULD identify owner, dependencies, affected domains, acceptance
criteria, evidence, the commit where the issue was observed, and current commit
when applicable.

The queue is singular across Program Director, domain lead, Session Manager,
and specialist views. Management layers sequence and route this queue; they do
not create parallel backlogs. For a specialist, next-work resolution MUST:

1. return that specialist's existing active assignment before any ready item;
2. otherwise return the first eligible ready item in deterministic queue order;
3. otherwise report the area idle without inventing work.

Assignment MUST fail closed when the specialist already owns another active
item. This invariant is serialized across different task files, not merely
protected by per-task revision locks. Blocked work is durable but not runnable;
it may be reconsidered explicitly when its dependency evidence changes.

Backlog health is read-only and reports exceptional conditions, including
multiple active assignments, stale assigned work, resolved dependencies on a
blocked item, missing or retired areas, old observation commits, ready work
without a live eligible specialist, and active work whose runtime session is
missing. Health never rewrites or reassigns work automatically.

Owner decisions affecting future work MUST be recorded durably. Chat messages
alone are insufficient. Project source, tests, approved configuration, and
accepted decision records outrank summaries and generated prompts.

Implementation checkpoint (2026-09-27): backlog items are revisioned JSON
records in the Session Manager's tracked worktree. The service and equivalent
CLI/MCP operations enforce transition, owner, dependency, one-active-item, and
concurrent-write rules; resolve assigned work before ready work; publish
assignments and blockers through durable messaging; surface active work and
health anomalies in doctor; and require a landed integration record at the
same commit before completion. Keeping management records in the manager
worktree prevents backlog activity from dirtying canonical main.

## 18. Checks and evidence

Projects declare checks as commands with optional resources and applicability.
TORCH executes them locally or through a configured provider and records a
receipt containing:

- check ID and definition version;
- exact Git commit;
- worktree and domain;
- command and relevant environment identity;
- start and finish time;
- exit status;
- coverage or subject description;
- artifact references;
- resource lease used;
- pass, fail, blocked, or incomplete result.

A passing receipt becomes stale when its tested commit changes or when policy
declares a relevant input changed. TORCH MUST never apply a receipt from one
commit to another merely because the branch name is unchanged.

Projects SHOULD retain scenario-level checks at meaningful system boundaries.
Fleet infrastructure itself MUST have acceptance tests that demonstrate both
success and failure behavior.

## 19. Shared-resource coordination

Resources such as browsers, GPUs, ports, databases, devices, API quotas, and
deployment accounts are declared with capacity and policy.

TORCH MUST support:

- FIFO queuing;
- lease ownership;
- acquisition and release;
- stale-owner detection;
- maximum hold policy;
- cancellation without leaking the resource;
- doctor visibility;
- project-specific bypass policy requiring explicit authority.

Fairness matters more than raw agent count. The Fleet SHOULD be sized around
the scarce machine and the cost of meaningful verification.

## 20. Integration queue and main protection

Pull requests are optional. TORCH provides a native integration queue with
records containing:

- source domain, branch, and commit;
- target branch;
- convergence state;
- required and observed check receipts;
- affected ownership boundaries;
- dependencies;
- authorization;
- current state and reason.

Example states include:

```text
needs_convergence
testing
blocked
ready
landing
landed
superseded
```

Before landing, TORCH MUST verify:

1. the source commit still exists and is recoverable;
2. the branch includes the required canonical state;
3. required checks passed for the exact source commit;
4. no required check was invalidated;
5. ownership and dependency conditions are satisfied;
6. the actor has landing authority;
7. the target has not advanced beyond policy tolerance.

Fleet policy MUST be enforceable without provider branch protection. A forge
adapter MAY mirror the same policy as defense in depth.

## 21. Doctor and observability

`torch doctor` is an observer and diagnostician, not an automatic repair tool.
It SHOULD report:

- domain-to-worktree and branch consistency;
- dirty files and in-progress Git operations;
- commits absent from the recoverability boundary;
- convergence drift measured by both count and age;
- pinned or actively measuring worktrees;
- session and presence state;
- prompt, roster, schedule, and generated-doc drift;
- missing dependencies or broken runtime integrations;
- message backlog and missing acknowledgements;
- resource holders and queue waiters;
- exact-SHA check validity;
- integration readiness;
- canonical Git and forge availability;
- local-only versus off-machine recoverability;
- installation-manifest inconsistencies.

Where runtimes expose usage data, observability SHOULD also report context
locality by Fleet identity: cached versus uncached input, cache creation and
read volume, compactions, resumed prompt size, and cost per verified item.
These metrics MUST identify whether they are measured or estimated and MUST
not treat a smaller prompt as success when verification quality declined.

Doctor output MUST distinguish observation from recommended action. Repair
commands require explicit invocation and normal authority checks.

Implementation checkpoint (2026-09-27): a read-only observation service and
`torch console snapshot` now expose project, health, identity, message,
backlog, check, resource, integration, delivery, schedule, and audit state
without initializing a missing database. The same snapshot exposes approved
ownership and neighbour relationships, managed worktree branch drift,
recoverability, acknowledgement state, tracked decisions, configured runtime
and delivery providers, and forge health. Context-locality output explicitly reports
`unavailable` until runtime usage samples exist, preventing estimates from
masquerading as measurements.

Identity-bound context telemetry now accepts provider measurements or explicit
estimates, never an unlabeled mixture. It records cached and uncached input,
cache creation and reads, compactions, resumed prompt size, micro-USD cost,
task/commit references, and verified item counts. Reports keep evidence classes
separate, derive cache-read ratio and cost per verified item, and warn when
usage has no verified outcome.

`torch doctor` additionally reports managed-worktree branch/commit consistency,
ahead and behind counts, the timestamp and age of the oldest missing canonical
commit, in-progress Git operations, configured runtime executable availability,
and the current commit's `ONE-DISK`, `LOCAL-REMOTE`, or `OFF-MACHINE`
recoverability grade. Each finding separates observed evidence from a
recommended action; doctor remains read-only.

## 22. Scheduling

TORCH recognizes two schedule classes.

**System schedules** survive AI sessions and may perform approved release,
backup, CI, mirroring, archival, dependency scan, or data-refresh work.

**Session schedules** exist while the Session Manager is active and may run
doctor, inspect drift, dispatch backlog, schedule QA, monitor resources,
monitor budget, or prepare wind-down.

Every schedule MUST declare:

- owner;
- lifetime;
- trigger;
- read-only or mutating behavior;
- command or action;
- required authority;
- retry and failure reporting;
- source of truth.

Schedules MUST be generated or validated from machine-readable configuration
so launcher code and prose cannot silently disagree.

Implementation checkpoint (2026-09-27): installed configuration carries
validated system and session schedules with owner, trigger, behavior,
shell-free action, authority, retry, failure recipient, and source-of-truth
fields. The service plans without mutation, blocks session schedules while the
Session Manager is offline, requires explicit approval for mutating actions,
records durable run evidence, retries deterministically, and reports failures
through durable blocker messages. CLI and MCP surfaces share the service.
System schedules can now use an owner-approved user-systemd launcher. The
launcher dispatches once per minute, evaluates the validated cron/interval
definitions in TORCH, suppresses duplicate minute runs, and refuses to run
after tracked configuration changes because its command is bound to the exact
configuration digest. Unit files are recorded in the installation ownership
manifest and removal refuses changed files. Installing that persistent
launcher on a real machine remains an explicit owner action.

## 23. Repository and forge operating modes

### 23.1 Local-only mode

Local-only mode is a production-supported baseline, not a demo. It requires:

```text
laptop
Git
TORCH
supported agent runtime
runtime/model credentials, if applicable
project repository
```

TORCH supplies worktrees, identities, messages, presence, backlog, decisions,
checks, resources, integration, and restart state locally.

If a project has no remote, TORCH SHOULD offer a local bare canonical Git store
under its machine-local project state. This preserves normal fetch/push and
shared-ref semantics.

Doctor MUST distinguish:

```text
ONE-DISK       commit exists in only one working repository
LOCAL-REMOTE   commit also exists in a local bare canonical store
OFF-MACHINE    commit exists on another machine or provider
```

A local bare repository is not an off-machine backup.

### 23.2 Forge-backed mode

A forge adapter MAY provide remote hosting, pull requests, code review UI,
hosted CI, issues, releases, branch protection, artifacts, and repository web
browsing. Each capability is independently optional.

Valid configurations include GitHub for mirroring while TORCH remains the
integration and check provider, or GitHub Actions for checks while TORCH keeps
its own backlog and integration queue.

### 23.3 Degraded operation

Loss of a forge MUST NOT destroy local identities, messages, commits, checks,
backlog, or coordination. Doctor reports delayed remote synchronization.
Whether integration may continue is a project policy decision.

### 23.4 Migration

Attaching or detaching a forge MUST preserve domain identities, worktrees,
backlog, decisions, and local state. TORCH verifies ref equivalence before
changing the canonical Git store.

## 24. Releases and deployments

Release storage and deployment are provider adapters. Examples include
filesystem, GitHub Releases, object storage, Vercel, or custom commands.

TORCH MUST distinguish:

```text
implemented
verified
integrated
release-ready
released
deployed
live-verified
```

Integration authority does not imply deployment authority. Project
configuration MUST state who may perform each transition. Secrets are resolved
at execution time from approved external stores and never copied into tracked
Fleet state.

Implementation checkpoint (2026-09-27): TORCH now persists this complete state
machine in the local control plane. Creation requires a clean, exact source
worktree tip and evidence; verification requires the configured exact-commit
check receipts; integration requires a landed request for that commit; and
release, deployment, and live verification require separately configured
provider capabilities, state-specific authority, evidence, successful adapter
receipts, and explicit owner approval. Fresh installations configure both
provider slots as `none`, so no external release or deployment can occur by
default. The CLI and read-only Fleet observation surface are implemented and
scenario-tested with a virtual adapter; no live release or deployment was
performed.

## 25. Security and trust boundaries

TORCH MUST:

- keep secrets outside repositories;
- record only secret references;
- scope runtime credentials and provider permissions;
- treat project content, messages, external documents, websites, logs, and
  imported text as data rather than higher-authority instructions;
- prevent peer messages from modifying Fleet policy or granting authority;
- require explicit owner approval for configured high-impact actions;
- log control-plane mutations with actor and project identity;
- avoid exposing one project's state to another;
- validate project IDs and filesystem targets before creating or removing
  worktrees;
- fail closed before destructive uninstall, upgrade, integration, or remote
  migration operations.

## 26. Self-hosting and version lifecycle

### 26.1 Stable manages candidate

TORCH's source repository MUST be managed by an installed stable TORCH release,
never by the source tree under development.

Example:

```text
installed TORCH 0.7
        │
        └── manages TORCH source for 0.8
```

The TORCH repository uses the same public `.torch/` configuration as any other
project and receives no hidden self-hosting exceptions.

### 26.2 Candidate isolation

Candidate releases MUST run side by side with stable using separate state,
socket, lock, port, and fixture namespaces. Candidate tests MUST not control
the live development fleet.

For a Git source checkout, candidate staging MUST bind the artifact to the
exact clean tracked commit. It may include the installed dependency tree needed
to execute acceptance, but MUST exclude arbitrary untracked files and reject
modified tracked input. Artifact-local relative dependency links are permitted;
links that escape the candidate root are refused. Non-Git inputs are treated as
already-prepared release artifacts and every contained entry is inventoried.

Candidate acceptance includes:

- initialize and analyze a fixture repository;
- review and install a proposed roster;
- create branches and worktrees;
- start identities through supported adapters;
- exchange manager-to-worker and peer-to-peer messages;
- query ownership;
- detect unsafe worktree states;
- complete backlog and integration lifecycles;
- acquire and release resources;
- capture, stop, and resume;
- detach and uninstall cleanly.

### 26.3 Atomic upgrade and rollback

Versions are installed side by side:

```text
~/.local/share/torch/versions/0.7.0/
~/.local/share/torch/versions/0.8.0/
```

Upgrade installs and validates the new version before atomically changing the
active pointer. Running processes may finish on the old version. Rollback
restores the previous pointer without rewriting project state. State migrations
MUST declare forward and rollback compatibility.

Activation also maintains a stable executable launcher at
`~/.local/bin/torch` (or an explicitly configured installation bin directory)
that resolves through the atomic active-version pointer. Candidate validation
hashes executable modes as well as bytes, rejects a non-executable TORCH binary,
and refuses to replace a launcher path not owned by that installation.

## 27. User interfaces

### 27.1 CLI

The target command surface includes:

```text
torch init
torch analyze
torch domains
torch install
torch detach
torch uninstall
torch up
torch up --fresh
torch up --only <domains>
torch down
torch capture
torch list
torch brief
torch doctor
torch backlog
torch message
torch status
torch checks
torch resources
torch integrate
torch schedules
torch candidate build
torch candidate test
torch upgrade
torch rollback
```

Commands MUST offer structured output where automation needs it.

### 27.2 Local Fleet Console

The operational console SHOULD expose:

- agents and presence;
- ownership and domain graph;
- worktrees, branches, drift, and recoverability;
- messages and acknowledgements;
- backlog and blockers;
- checks and exact tested commits;
- integration queue;
- resource holders and waiters;
- decisions, schedules, releases, and provider health.

The console is an operational view over the same core service, not a separate
source of truth.

### 27.3 Public website

The public website MUST be redesigned around the new product. It MUST NOT
describe Nostr task locks, relay coordination, the old scheduler, or a catalog
of generic agents.

Its primary story is:

```text
owner request
→ Session Manager routing
→ domain-owned worktrees
→ direct coordination
→ exact-commit verification
→ controlled convergence
→ canonical main
```

The site SHOULD separate product explanation and documentation from the local
Fleet Console. A distinctive routing or dispatch-board visualization should
demonstrate the system more clearly than a wall of feature cards.

Recommended product language:

> One repository. A coordinated AI engineering team.

TORCH SHOULD be treated as the product name rather than retaining the legacy
"Task Orchestration via Relay-Coordinated Handoff" expansion.

## 28. Delivery plan

### Stage 0: Preserve and specify

- archive the legacy Nostr main line;
- preserve the development-network experiment separately;
- establish a clean rewrite branch;
- accept this specification and record any amendments;
- define scenario IDs and fixture repositories.

Exit gate: the owner approves the product boundary and legacy preservation
plan.

Implementation checkpoint (2026-09-27): the former Nostr product is preserved
at `legacy/nostr-torch`, the development-network experiment is preserved at
`legacy/development-network-v2`, and active development occurs on
`rewrite/portable-agent-fleet`. Once the replacement kernel and its acceptance
suite were established, Nostr-era runtime code, dashboards, generated output,
task logs, fixtures, and tests were removed from the rewrite branch rather
than carried as a misleading second product. The legacy branches remain the
recovery and history boundary.

### Stage 1: Portable kernel

- configuration schema and loader;
- project identity and XDG state layout;
- read-only `init` and `analyze` scaffolding;
- install manifest;
- detach, uninstall dry-run, and doctor foundation;
- Git repository and worktree inspection.

Exit gate: installation and complete reversal succeed on a fixture repository
without modifying user code.

### Stage 2: Project decomposition

- reconnaissance and architecture graph;
- domain proposal and collision analysis;
- human review artifact;
- roster, prompt, backlog, and worktree generation;
- bootstrap acceptance test.

Exit gate: two structurally different fixture repositories receive defensible,
reviewable organizations.

Implementation checkpoint (2026-09-27): `torch analyze` and `torch design`
accept `--repo` plus repeatable `--spec` inputs. Markdown specifications are
read without execution, reduced to evidence-linked responsibilities and
domain signals, fingerprinted, and checked again at approval. A spec-first
fixture demonstrates project-specific responsibilities with intentionally
unresolved path ownership; a separate repository fixture continues to prove
code-derived architecture and collision boundaries. Both paths remain
read-only until an approved install.

`torch bootstrap` now emits the provider-independent Session Architect brief.
Its scenario proves that a mixed code/spec project exposes omitted components
and unmatched goals for AI reasoning, forbids copying COMBATRIG or a generic
catalog, and preserves owner-only approval without mutating the project.

`torch architect plan`, `validate`, and explicitly authorized `run` now carry
that brief through isolated Claude or Codex planning and semantic validation.
Automated coverage uses virtualized provider output; no live model usage is
implied by the passing scenario.

### Stage 3: Claude reference fleet

- control-plane service and MCP server;
- Claude adapter;
- identity, presence, messages, acknowledgement, and lifecycle;
- Session Manager and domain startup;
- capture, wind-down, and resume.

Exit gate: a local Claude fleet completes a bounded multi-domain change and
resumes after shutdown.

### Stage 4: Verification and integration

- checks and exact-SHA receipts;
- resource queues and leases;
- doctor completeness;
- convergence workflow;
- integration queue and main policy;
- local bare canonical Git store.

Exit gate: a local-only fleet can take a change from assignment through tested
integration without GitHub or hosted CI.

### Stage 5: Runtime portability

- Codex adapter;
- mixed-runtime fleet;
- CLI fallback for MCP-limited environments;
- capability reporting and degraded behavior.

Exit gate: Claude and Codex occupy persistent domains in one Fleet and
coordinate through TORCH rather than native vendor messaging.

Implementation checkpoint (2026-09-27): the Codex adapter, mixed-runtime
planning, invocation-scoped identity-bound MCP configuration for every create
and resume launch, JSONL runtime-ID capture, durable-first steering, and
explicit degraded capabilities are implemented and scenario-tested with
virtualized runners plus a real local stdio MCP handshake. Claude receives an
ephemeral `--mcp-config`; Codex receives invocation-local `mcp_servers`
overrides, so TORCH does not rewrite either runtime's global configuration.
The exit gate remains open until an
owner-authorized live Claude/Codex acceptance run demonstrates coordination;
the automated suite intentionally incurs no provider usage.

### Stage 6: Self-hosting

- stable/candidate isolation;
- candidate fixture suite;
- atomic upgrade and rollback;
- TORCH's own approved roster and worktrees.

Exit gate: stable TORCH manages development, testing, and promotion of its
successor in local-only mode.

Implementation checkpoint (2026-09-27): isolated version installation,
reserved validation receipts, declared state compatibility, an atomic active
symlink, activation journaling, interruption reconciliation, exact rollback,
and approval-gated CLI operations are implemented and scenario-tested. The
candidate CLI requires named acceptance evidence, including the implemented
tracked backlog-through-integration lifecycle. The exit gate remains open
until an installed stable TORCH manages this source repository; candidate code
does not receive a hidden self-hosting exception.

### Stage 7: COMBATRIG re-import

- express COMBATRIG domains, prompts, resources, checks, schedules, and release
  boundaries through portable configuration;
- replace project-owned generic fleet scripts with installed TORCH operations;
- compare behavior against the current working fleet;
- retain COMBATRIG-specific gates and deployment as project adapters.

Exit gate: COMBATRIG operates without special-case orchestration in TORCH core.

Implementation checkpoint (2026-09-27): a read-only COMBATRIG importer now
maps the legacy dispatcher to the portable Session Manager and preserves the
observed area prompts and hashes, branch/worktree names, checks, scarce browser
capacity, schedule lifetimes, release authority, and backlog inventory. The
captured report at `reports/audit/combatrig-import-2026-09-27.json` found 33 areas
and 570 backlog records without modifying COMBATRIG. It remains intentionally
pending: 56 blocking ownership/exclusion gaps affect all 33 areas. The exit
gate remains open until those owner-reviewed boundaries are resolved and
COMBATRIG is safely installed and operated through portable TORCH.

### Stage 8: Product surface

- new public website and documentation;
- local Fleet Console;
- additional runtime and forge adapters;
- standalone distribution packaging.

Exit gate: the public surface accurately demonstrates behavior proven by the
released product.

Implementation checkpoint (2026-09-27): the Nostr-era landing page and
dashboard were removed. A new responsive public surface explains the
request-to-main flow through an interactive dispatch board, publishes the
current qualification ledger, and presents repository/spec-aware startup. A
separate loopback Fleet Console consumes the read-only observation service,
uses a restrictive content-security policy, and labels context locality as
unmeasured until evidence arrives. Local HTTP, desktop, and mobile rendering
are verified; public deployment and standalone distribution remain open.

## 29. Required acceptance configurations

### A. Laptop-only

```text
existing or new Git repository
no forge
Fleet-created local bare canonical repository
one laptop
Claude or Codex
```

The complete lifecycle from analysis through integration, restart, and detach
MUST pass.

### B. Existing local repository

Installation after project history exists MUST preserve all source history,
branches, untracked user files, and preexisting configuration. Uninstall MUST
restore the pre-install integration state.

### C. Forge-backed

An existing GitHub or equivalent remote MAY supply selected capabilities while
TORCH semantics remain authoritative.

### D. Local to forge-backed

Attaching a forge later MUST preserve worktrees, identities, backlog,
decisions, and messages.

### E. Forge-backed to local

Detaching the forge MUST leave local development operational.

### F. Forge outage

Local sessions, messages, commits, checks, backlog, and integration permitted
by policy MUST continue. Pending remote synchronization is visible.

### G. Mixed runtimes

At least two runtime adapters MUST exchange durable messages, query the same
roster, and coordinate one shared-boundary change.

### H. TORCH builds TORCH

An installed stable release MUST manage the next candidate using local-only
Git and TORCH's own control plane.

### I. COMBATRIG compatibility

The portable system MUST reproduce the essential COMBATRIG behavior without
hard-coded COMBATRIG paths or names.

## 30. COMBATRIG extraction map

The following files are behavioral references, not copy mandates:

| COMBATRIG surface | Portable TORCH responsibility |
| --- | --- |
| `tools/dev/fleet.sh` | lifecycle orchestration and first Claude adapter |
| `tools/dev/fleet-capture.mjs` | runtime-ID capture |
| `tools/dev/brief.mjs` | configuration-derived identity brief |
| `tools/dev/sessions.mjs` | presence and session registry |
| `tools/dev/doctor.mjs` | Git, worktree, session, resource, and risk diagnostics |
| `tools/dev/backlog.mjs` | durable work queue |
| `docs/agents/roster.json` | roster schema, scope, exclusions, and neighbors |
| `docs/agents/prompts/` | common plus domain prompt composition |
| `docs/DISPATCH.md` | Session Manager routing and reporting policy |
| `docs/WORKTREES.md` | isolation, process ownership, measurement, and resource rules |
| `docs/agents/OPERATIONS.md` | lifecycle, schedules, restart, and release separation |
| `docs/agents/WIND-DOWN.md` | coordinated shutdown |
| `docs/agents/RESUME-BRIEF.md` | durable restart handoff |
| `.claude/settings.json` | Claude-specific hook adapter |
| `tools/test/serve.mjs` | project-specific resource lease lessons |
| `tools/dev/release.sh` | project-specific release adapter example |

Extraction classification is mandatory:

**Portable core** includes roster semantics, briefing, worktree lifecycle,
backlog, doctor architecture, messaging, checks, integration, and resource
coordination.

**Runtime adapter** includes session creation, naming, resume, steering,
listing, stopping, ID capture, and lifecycle hooks.

**Project configuration or adapter** includes COMBATRIG domains, tests, port
allocation, GPU/browser policy, model assignments, secrets, deployment, asset
pipelines, and release schedule.

**Do not carry forward** includes duplicated prose configuration, hard-coded
home paths, COMBATRIG prefixes, implicit external cron state, or assumptions
that native Claude messaging is the Fleet API.

## 31. Open implementation decisions

These choices remain open but MUST be resolved through short architecture
decisions before their implementation stage:

1. SQLite schema and event-retention policy for machine-local state.
2. Control-plane transport: Unix socket, localhost HTTP, or a combination.
3. Exact project identity derivation and repository-move behavior.
4. Runtime process supervision across Linux, macOS, and Windows.
5. Configuration generation versus checked-in derived files.
6. Adapter capability negotiation and minimum conformance levels.
7. Check-input invalidation beyond Git commit identity.
8. Local canonical-remote naming when a project already has `origin`.
9. Multi-machine authentication and encryption.
10. Distribution and update signing.
11. Organization graph, configurable role authority, hierarchy change
    proposals, and safe promotion or reassignment of persistent identities.

None of these decisions may weaken the core invariants or make a forge
mandatory.

## 32. Definition of the first usable release

The first usable TORCH release is complete only when a user can run:

```bash
cd an-existing-project
torch init
torch analyze
torch install --runtime claude
torch up
```

review and approve a proposed organization, assign a real task through its
owner-facing coordination role, observe at least two domain managers
coordinate, record verification against exact commits, integrate through TORCH
policy, stop the fleet, resume it without losing identity or unfinished work,
and detach it without damaging the repository.

That lifecycle MUST pass with no Nostr relay, no GitHub account, no hosted CI,
no hosted database, and no project-local copy of the TORCH engine.