# Orch Markdown Test Plan

## Purpose

This directory contains the human-readable Markdown test plan for the `orch` CLI.

It complements automated Go tests. The goal is to preserve the user-visible scheduler contract in a form that can be reviewed, extended, and executed manually without re-deriving command behavior from implementation code.

## Directory Rules

- one folder per `orch` leaf command or shared area
- each folder keeps a `README.md` entrypoint
- command folders use `README.md` as an index only
- each command test case lives in its own Markdown file named after the case slug
- no numeric test IDs
- each command case is identified by its concrete file path

Case file naming pattern:

```text
<case-slug>.md
```

## Authoring Principles

- focus on externally visible CLI behavior rather than store internals
- prefer stable command sequences that a new agent can replay against a temp database
- document both success contracts and failure boundaries
- reuse scenarios from automated `orch` integration tests before inventing new cases
- keep terminology consistent with the scheduler concepts exposed by `orch`: run, task, dependency, attempt, blocked task, worktree, and council review

## Common Execution Model

Most cases in this directory assume the same baseline:

1. create an isolated temporary directory
2. choose a database path such as `TMPDIR/coord.db`
3. run the target `orch` command sequence with `--db TMPDIR/coord.db --json`
4. when a case needs worker-side state transitions, drive them through `inbox` against the same database

Unless a case says otherwise:

- commands should use `--json`
- assertions should check both exit code and JSON payload
- `orch` may be pointed at an empty database path; schema bootstrapping happens automatically on open

## Folder Map

- `README.md`: global conventions and glossary
- `ROADMAP.md`: document progress, planned case backlog, and authored-case register
- `_shared/README.md`: reusable fixtures, JSON assertions, exit-code rules, and worktree conventions
- `workflows/README.md`: cross-command end-to-end scenarios
- per-command folders: one leaf-command directory per implemented `orch` command surface

## Glossary

- `run`: one coordinated execution for a user request
- `task`: one schedulable unit of work inside a run
- `dependency`: an edge that gates one task on another
- `attempt`: one execution try for a task
- `dispatch`: the act of materializing a task into an inbox thread
- `workspace`: the branch and worktree assigned to a code-writing attempt
- `blocked task`: a task whose active attempt requires clarification or another external decision
- `council review`: a higher-level workflow built on top of `orch` that dispatches fixed reviewer roles and tallies recommendations

## Relationship To Automated Tests

The current best executable reference is [integration_test.go](../../../packages/orch-runtime/internal/cli/orch/integration_test.go).

When this Markdown plan expands:

- prefer matching an existing automated scenario first
- record any additional manual-only contract coverage explicitly in the relevant command case file
- keep [ROADMAP.md](./ROADMAP.md) synchronized with authored files and case slugs