Ratchet

# Executable spec for the /ratchet skill — permanent progress gates (BC3 Loop).
# /ratchet is the Brownian Ratchet: Chaos × Filter → Ratchet. It records passed
# loop-step gates to .agents/ao/chain.jsonl so progress is locked and monotonic —
# you cannot un-ratchet. Hexagon: domain; consumes validation, vibe, post-mortem
# (the filter outputs it locks); produces .agents/rpi/*.md + chain entries. (soc-qk4b.2)

Feature: Ratchet locks loop progress permanently
  As the loop's progress lock
  I want passed gates recorded to a monotonic chain
  So that progress is permanent — chaos is filtered, then ratcheted, never undone

  Scenario: Chaos is filtered, then ratcheted
    Given multiple attempts (chaos) that pass their validation gate (filter)
    When the gate result is ratcheted
    Then the progress is locked permanently in the chain

  Scenario: A passed gate is recorded to the chain
    When /ratchet records a completed step (research, plan, implement, vibe, post-mortem)
    Then a chain entry is appended to .agents/ao/chain.jsonl with step, status, and output

  Scenario: Gate state is checkable before advancing
    When /ratchet checks a step
    Then it reports whether that gate is satisfied
    And the loop does not advance past an unsatisfied required gate

  Scenario: A recorded gate cannot be un-ratcheted
    Given a step already recorded as completed in the chain
    Then progress is monotonic — the recorded gate is not reversed


#!/usr/bin/env bash
set -euo pipefail
SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0; FAIL=0
check() { if bash -c "$2"; then echo "PASS: $1"; PASS=$((PASS + 1)); else echo "FAIL: $1"; FAIL=$((FAIL + 1)); fi; }

check "SKILL.md exists" "[ -f '$SKILL_DIR/SKILL.md' ]"
check "SKILL.md has YAML frontmatter" "head -1 '$SKILL_DIR/SKILL.md' | grep -q '^---$'"
check "name is ratchet" "grep -q '^name: ratchet' '$SKILL_DIR/SKILL.md'"
check "mentions gates" "grep -qi 'gates' '$SKILL_DIR/SKILL.md'"
check "mentions progress" "grep -qi 'progress' '$SKILL_DIR/SKILL.md'"
check "mentions record" "grep -qi 'record' '$SKILL_DIR/SKILL.md'"
check "mentions chain storage" "grep -q 'chain' '$SKILL_DIR/SKILL.md'"

echo ""; echo "Results: $PASS passed, $FAIL failed"
[ $FAIL -eq 0 ] && exit 0 || exit 1


---
name: ratchet
description: Record Brownian Ratchet gates.
practices:
- dora-metrics
- refactoring
- continuous-integration
hexagonal_role: domain
consumes:
- validation
- vibe
- post-mortem
produces:
- .agents/rpi/*.md
context_rel:
- kind: shared-kernel
  with: standards
skill_api_version: 1
user-invocable: false
context:
  window: isolated
  intent:
    mode: none
  sections:
    exclude:
    - HISTORY
    - INTEL
    - TASK
  intel_scope: none
metadata:
  tier: background
  dependencies: []
  internal: true
output_contract: 'stdout: gate check result'
---
# Ratchet Skill

Track progress through the RPI workflow with permanent gates.

**Note:** `/ratchet` tracks and locks progress. It does not “run the loop” by itself—pair it with `/crank` (epic loop) or `/swarm` (Ralph loop) to actually execute work.

## The Brownian Ratchet

```
Progress = Chaos × Filter → Ratchet
```

| Phase | What Happens |
|-------|--------------|
| **Chaos** | Multiple attempts (exploration, implementation) |
| **Filter** | Validation gates (tests, /vibe, review) |
| **Ratchet** | Lock progress permanently (merged, closed, stored) |

**Key insight:** Progress is permanent. You can't un-ratchet.

## Execution Steps

Given `/ratchet [command]`:

### status - Check Current State

```bash
ao ratchet status 2>/dev/null
```

Or check the chain manually:
```bash
cat .agents/ao/chain.jsonl 2>/dev/null | tail -10
```

### check [step] - Verify Gate

```bash
ao ratchet check <step> 2>/dev/null
```

Steps: `research`, `plan`, `implement`, `vibe`, `post-mortem`

### record [step] - Record Completion

```bash
ao ratchet record <step> --output "<artifact-path>" 2>/dev/null
```

Or record manually by writing to chain:
```bash
echo '{"step":"<step>"