# Orch Log

> Append, read, and verify the append-only orchestration event log (.orch/log.jsonl). Provides append.py (lock + hash chain + schema validation), read.py (filtered queries), and verify.py (hash-chain integrity). Loaded by orchestrators and workers that emit or inspect events. Not user-invocable — callers run the scripts directly.

- **Type:** Skill
- **Install:** `agentstack add skill-zig999-siegard-code-orch-log`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zig999](https://agentstack.voostack.com/s/zig999)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [zig999](https://github.com/zig999)
- **Source:** https://github.com/zig999/siegard-code/tree/main/dist/.claude/skills/orch-log

## Install

```sh
agentstack add skill-zig999-siegard-code-orch-log
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# orch-log

Event log skill: append, read, and verify the orchestration JSONL log.

## scripts/append.py

Emits an event to the append-only log with lock, hash chain, and schema validation.

### Usage

```bash
python3 .claude/skills/orch-log/scripts/append.py \
  --agent  \
  --event-type  \
  [--task-id ] \
  [--attempt ] \
  [--data '']
```

### Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `--agent` | Yes | Agent identifier emitting the event |
| `--event-type` | Yes | Event type (see valid types below) |
| `--task-id` | No | Task ID (omit for phase/workflow events) |
| `--attempt` | No | Attempt number, default `1` |
| `--data` | No | JSON object payload, default `{}` |

### Output

On success (exit 0): JSON object of the created event written to stdout.

On error (exit 1): JSON error envelope:
```json
{"status": "error", "reason": "", "detail": ""}
```

Error reason codes:
- `invalid_json` — `--data` is not valid JSON or not an object
- `unknown_event_type` — `--event-type` not in the 21-type enum
- `validation_error` — payload fails schema validation
- `internal_error` — unexpected I/O or lock failure

### Example

```bash
python3 .claude/skills/orch-log/scripts/append.py \
  --agent orchestrator \
  --event-type task_created \
  --task-id t_001 \
  --data '{"phase":"dev","tier":"standard","type":"impl","spec":"implement X","deps":[]}'
```

## scripts/read.py

Reads events from the log with optional filters. Each matching event is printed as one JSON line to stdout.

### Usage

```bash
python3 .claude/skills/orch-log/scripts/read.py \
  [--from-seq N] \
  [--tail N] \
  [--task-id ] \
  [--event-type ] \
  [--phase ]
```

### Parameters

| Parameter | Description |
|-----------|-------------|
| `--from-seq N` | Return events with seq >= N (default: 0 = all) |
| `--tail N` | Return only the last N events (applied after other filters) |
| `--task-id` | Filter by task ID |
| `--event-type` | Filter by event type |
| `--phase` | Filter by data.phase field |

Multiple filters are applied as AND. Output: one JSON object per line (empty output = no matches). Exit 0 on success, 1 on corrupted log.

### Examples

```bash
# All events
python3 .claude/skills/orch-log/scripts/read.py

# Last 20 events
python3 .claude/skills/orch-log/scripts/read.py --tail 20

# All task_created events in phase dev
python3 .claude/skills/orch-log/scripts/read.py --event-type task_created --phase dev
```

## scripts/verify.py

Verifies hash-chain integrity of the log. Output is a single JSON object.

### Usage

```bash
python3 .claude/skills/orch-log/scripts/verify.py [--mode strict|audit]
```

### Modes

| Mode | Behavior | Exit code |
|------|----------|-----------|
| `strict` (default) | Stops at first error | 0 ok, 1 error |
| `audit` | Collects all errors, never modifies log | Always 0 |

### Output schema

```json
{
  "ok": true,
  "message": "...",
  "mode": "strict",
  "events_verified": 42,
  "first_error_seq": null,
  "error_details": []
}
```

Use `audit` for investigation; use `strict` at orchestrator startup (architecture rule R1).

## Valid event types

Task lifecycle (8):
```
task_created   task_claimed       task_progress         task_completed
task_failed    task_scheduled_retry  task_retried       task_dlq
```

Phase lifecycle (7):
```
phase_declared         phase_entered              phase_exit_criterion_met
phase_exit_approved    phase_transitioned         phase_paused
phase_resumed
```

Management and operations (6):
```
circuit_breaker_tripped   escalation   human_response
snapshot                  log_recovered   preflight_failed
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zig999](https://github.com/zig999)
- **Source:** [zig999/siegard-code](https://github.com/zig999/siegard-code)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zig999-siegard-code-orch-log
- Seller: https://agentstack.voostack.com/s/zig999
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.