# dagztagz/dagz-scaffold architecture

> Architecture diagram of the GitHub repository dagztagz/dagz-scaffold, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dagztagz/dagz-scaffold
- Repository: https://github.com/dagztagz/dagz-scaffold

## Overview

Dagz-Scaffold inspects coding-agent work: a user starts a task persist, Grok produces a durable run packet, and the Python scorer and ship gate decide whether it is acceptable. The packet preserves the plan, changed code, command evidence, critic verdict, and score claim. Major branches include task-specific verification contracts, optional safe command replay, and staged-file checks for secrets or live runs. The workflow wiring is supported by the README and sampled harness code; the skill directories are documented capabilities, but their internal behavior was not sampled.

Main entry points: [`harness/score.py`](https://github.com/dagztagz/dagz-scaffold/blob/main/harness/score.py) (Packet scorer), [`harness/run.py`](https://github.com/dagztagz/dagz-scaffold/blob/main/harness/run.py) (Persist runner), [`harness/ship_gate.py`](https://github.com/dagztagz/dagz-scaffold/blob/main/harness/ship_gate.py) (Ship gate), [`tasks`](https://github.com/dagztagz/dagz-scaffold/tree/main/tasks) (Task definition)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_persist["Persist workflow"]
  node_task["Task definition"]
  node_persist_skill["Persist guidance<br/>[persist]"]
  node_runner["Persist runner<br/>[run.py]"]
  node_critic_skill["Critic guidance<br/>[critic]"]
  node_run_packet["Run packet"]
end

subgraph group_inspection["Run inspection"]
  node_score["Packet scorer<br/>[score.py]"]
  node_contract["Task contracts<br/>[task_contract.py]"]
  node_schema["Score schema<br/>[run.schema.json]"]
  node_replay["Evidence replay<br/>[replay.py]"]
  node_result["Score result"]
end

subgraph group_release["Ship gate"]
  node_ship_gate["Ship gate<br/>[ship_gate.py]"]
  node_gate_skill["Gate guidance<br/>[ship-gate]"]
end

node_user(("Task author"))
node_grok_cli["Grok Build CLI"]
node_xai(("xAI service"))
node_git_index[("Git index")]

node_user -->|"starts persist"| node_runner
node_task -->|"supplies task"| node_runner
node_persist_skill -->|"guides persist"| node_grok_cli
node_runner -->|"invokes"| node_grok_cli
node_grok_cli -.->|"uses account"| node_xai
node_grok_cli -->|"writes artifacts"| node_run_packet
node_critic_skill -->|"guides critique"| node_grok_cli
node_runner -->|"scores run"| node_score
node_score -->|"reads packet"| node_run_packet
node_score -->|"loads contract"| node_contract
node_contract -->|"reads task"| node_task
node_score -->|"validates against"| node_schema
node_score -.->|"optionally replays"| node_replay
node_score -->|"produces grade"| node_result
node_runner -->|"checks grade"| node_result
node_user -->|"requests gate"| node_ship_gate
node_gate_skill -->|"guides gate"| node_grok_cli
node_ship_gate -->|"checks run"| node_score
node_ship_gate -.->|"optionally scans"| node_git_index
node_ship_gate -->|"reports pass or block"| node_result

click node_task "https://github.com/dagztagz/dagz-scaffold/tree/main/tasks"
click node_persist_skill "https://github.com/dagztagz/dagz-scaffold/tree/main/.grok/skills/persist"
click node_runner "https://github.com/dagztagz/dagz-scaffold/blob/main/harness/run.py"
click node_critic_skill "https://github.com/dagztagz/dagz-scaffold/tree/main/.grok/skills/critic"
click node_run_packet "https://github.com/dagztagz/dagz-scaffold/tree/main/runs"
click node_score "https://github.com/dagztagz/dagz-scaffold/blob/main/harness/score.py"
click node_contract "https://github.com/dagztagz/dagz-scaffold/blob/main/harness/task_contract.py"
click node_schema "https://github.com/dagztagz/dagz-scaffold/blob/main/harness/schema/run.schema.json"
click node_replay "https://github.com/dagztagz/dagz-scaffold/blob/main/harness/replay.py"
click node_ship_gate "https://github.com/dagztagz/dagz-scaffold/blob/main/harness/ship_gate.py"
click node_gate_skill "https://github.com/dagztagz/dagz-scaffold/tree/main/.grok/skills/ship-gate"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_task,node_persist_skill,node_runner,node_critic_skill,node_run_packet toneBlue
class node_score,node_contract,node_schema,node_replay,node_result,node_git_index toneAmber
class node_ship_gate,node_gate_skill toneMint
class node_user toneRose
class node_grok_cli,node_xai toneIndigo
```

## Components

### Persist workflow

- [Task definition](https://github.com/dagztagz/dagz-scaffold/tree/main/tasks): `tasks`
- [Persist guidance](https://github.com/dagztagz/dagz-scaffold/tree/main/.grok/skills/persist): `.grok/skills/persist`
- [Persist runner](https://github.com/dagztagz/dagz-scaffold/blob/main/harness/run.py): `harness/run.py`
- [Critic guidance](https://github.com/dagztagz/dagz-scaffold/tree/main/.grok/skills/critic): `.grok/skills/critic`
- [Run packet](https://github.com/dagztagz/dagz-scaffold/tree/main/runs): `runs`

### Run inspection

- [Packet scorer](https://github.com/dagztagz/dagz-scaffold/blob/main/harness/score.py): `harness/score.py`
- [Task contracts](https://github.com/dagztagz/dagz-scaffold/blob/main/harness/task_contract.py): `harness/task_contract.py`
- [Score schema](https://github.com/dagztagz/dagz-scaffold/blob/main/harness/schema/run.schema.json): `harness/schema/run.schema.json`
- [Evidence replay](https://github.com/dagztagz/dagz-scaffold/blob/main/harness/replay.py): `harness/replay.py`
- **Score result**

### Ship gate

- [Ship gate](https://github.com/dagztagz/dagz-scaffold/blob/main/harness/ship_gate.py): `harness/ship_gate.py`
- [Gate guidance](https://github.com/dagztagz/dagz-scaffold/tree/main/.grok/skills/ship-gate): `.grok/skills/ship-gate`

### Other components

- **Task author**
- **Grok Build CLI**
- **xAI service**
- **Git index**

## Connections

- Task author → Persist runner: starts persist
- Task definition → Persist runner: supplies task
- Persist guidance → Grok Build CLI: guides persist
- Persist runner → Grok Build CLI: invokes
- Grok Build CLI → xAI service: uses account
- Grok Build CLI → Run packet: writes artifacts
- Critic guidance → Grok Build CLI: guides critique
- Persist runner → Packet scorer: scores run
- Packet scorer → Run packet: reads packet
- Packet scorer → Task contracts: loads contract
- Task contracts → Task definition: reads task
- Packet scorer → Score schema: validates against
- Packet scorer → Evidence replay: optionally replays
- Packet scorer → Score result: produces grade
- Persist runner → Score result: checks grade
- Task author → Ship gate: requests gate
- Gate guidance → Grok Build CLI: guides gate
- Ship gate → Packet scorer: checks run
- Ship gate → Git index: optionally scans
- Ship gate → Score result: reports pass or block