75 lines
3.1 KiB
Markdown
75 lines
3.1 KiB
Markdown
# 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
|