dsh-spec-gate

Readme

# dsh-spec-gate

Specification gate plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh). Turns vague requirements into locked, verifiable specifications before work begins — and refuses to hand over deliverables that don't meet them.

Borrows two ideas from Ouroboros, adapted for content production (writing / analysis / reports):

- **Interview gate**: vague request → Socratic questioning to expose hidden assumptions → ambiguity score (converged at ≤ 0.2 before proceeding)
- **Acceptance gate**: before delivery, mechanically check the draft against the locked Seed (keyword coverage, hard constraints, word count) + semantic alignment hint for the agent

Pairs with [dsh-cybernetics](https://github.com/boomzikazita/dsh-cybernetics): acceptance failures are written to the events log and feed the cybernetic feedback loop.

## Tools

| Tool | Purpose |
|------|---------|
| `spec_interview_assess` | Ambiguity scoring: judge 8 dimensions (audience / purpose / format / data / scope / tone / acceptance / deadline) as clear / assumed / missing; returns score + questions to ask |
| `spec_seed_build` | Lock an immutable Seed (goal / dimensions / acceptance criteria / constraints) after the interview converges; hash-keyed, never overwritten |
| `spec_gate_evaluate` | Pre-delivery acceptance: mechanical checks against the Seed + AC coverage hints; fails closed |

## Install

```bash
dsh plugin --profile web add github:boomzikazita/dsh-spec-gate
```

## Configure

```yaml
# cordis.patch.yml (or the plugin's own bundle patch)
- insert:
    - id: spec-gate
      name: 'dsh-spec-gate'
      config:
        seedsDir: '~/.dsh/spec-gate/seeds'
        eventsLog: '~/.dsh/spec-gate/events.jsonl'
        convergeThreshold: 0.2
        hardGate: false  # block write/edit before a Seed exists (default off)
```

## Usage Flow

1. Vague request arrives → run `spec_interview_assess` → clarify missing dimensions until score ≤ 0.2
2. Lock the spec: `spec_seed_build` → returns `seed_id`
3. Produce the deliverable
4. Verify: `spec_gate_evaluate(draft, seed_id)` → only hand over on pass

## License

MIT