# Harness — orientation

audience: AI coding agents first. Facts that cost a session to rediscover. BLUF.

Repo-wide mandates (worktree isolation, UI rules, landing) live in the repo-root `AGENTS.md`. This file is harness orientation only — do not merge the two.

## Layout

| What | Path |
|---|---|
| ADW entrypoints (one file per workflow) | `factory/adw_*.py` |
| Engine internals | `factory/adw_modules/` |
| Per-agent system + user prompt templates | `factory/prompt_engineering/<agent>/` |
| Tests | `factory/tests/` |
| Default config | `factory/sssf.config.yaml` |

Config resolution, in order: `--config`, else `<repo>/.factory/sssf.config.yaml`, else the shipped default above. A project overrides only the keys it cares about.

## Timeout and process lifecycle

Factory timeout code MUST expose these states:

1. `starting` — wall timeout only. Idle timeout MUST NOT start before first stdout.
2. `streaming` — wall + idle timeout, measured with monotonic time.
3. `terminating` — signal process group with `SIGTERM`; after bounded grace, use `SIGKILL`.
4. `terminal` — drain stdout/stderr and write one terminal receipt exactly once.

Tests MUST inject clock, sleeper, and process seams. Use fake time for state transitions, timeout boundaries, and output preservation. Keep one real-process integration test for process-group signaling and drain behavior. NEVER make broad-suite load or multi-second sleeps the primary correctness oracle.

```text
DO NOT: sleep 30s → hope scheduler reproduces race → rerun broad suite
TARGET: advance fake monotonic clock → assert state + signal + preserved output
```

## An agent cannot edit the machinery that judges it

`adw_modules/permissions.py` bars every factory agent from writing under `modules/harness/factory/**`. That is deliberate: an agent must not edit the gates, prompts or phase logic that grade its own work. **Consequence: the factory cannot build its own producer-side code** — changes here are made by hand or by a separate agent, never by a factory run.

## Trace database

`/home/user/.local/state/overdeck/factory/sssf.db`. Schema and every writer live in `adw_modules/tracer.py`; the `/factory` page in the web UI reads it.

Schema changes, no exceptions:
- New table → add it to the `CREATE TABLE ... IF NOT EXISTS` block.
- Additive column on a table that already shipped → add it to `MIGRATIONS`.
- **NEVER edit a shipped `CREATE TABLE`** — existing databases already ran it, so the edit silently never applies.

## Tests

```bash
python3 -m pytest modules/harness/factory/tests/ -q
```

Run the full suite, not a single file — the phase, gate and permission paths are coupled.