johno/gastown
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: Radically condense documentation (10k → 548 lines)

Browse Source 
Replace 28 sprawling docs with 2 focused ones:
- README.md: User-focused, top-down intro (268 lines)
- docs/reference.md: Technical reference (280 lines)

Key changes:
- Top-down structure (formulas first, not beads)
- Bullets/tables over prose
- Human commands (start/shutdown/attach) vs agent commands
- All 6 roles documented (Overseer through Polecat)
- Ice-9/protomolecule easter eggs for the Expanse/Vonnegut fans
- Prefix-based beads routing explanation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-26 23:37:47 -08:00
parent fa0dfc324e
commit dbd99f4c8d
30 changed files with 514 additions and 11153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
docs/polecat-lifecycle.md
View File

@@ -1,130 +0,0 @@
# Polecat Lifecycle
> Polecats restart after each molecule step. This is intentional.
## Execution Model
| Phase | What Happens |
|-------|--------------|
| **Spawn** | Worktree created, session started, molecule slung to hook |
| **Step** | Polecat reads hook, executes ONE step, runs `gt mol step done` |
| **Restart** | Session respawns with fresh context, next step on hook |
| **Complete** | Last step done → POLECAT_DONE mail → cleanup wisp created |
| **Cleanup** | Witness verifies git clean, kills session, burns wisp |
```
spawn → step → restart → step → restart → ... → complete → cleanup
└──────────────────────────────────────┘
(fresh session each step)
```
## Why Restart Every Step?
| Reason | Explanation |
|--------|-------------|
| **Atomicity** | Each step completes fully or not at all |
| **No wandering** | Polecat can't half-finish and get distracted |
| **Context fresh** | No accumulation of stale context across steps |
| **Crash recovery** | Restart = re-read hook = continue from last completed step |
**Trade-off**: Session restart overhead. Worth it for reliability at current cognition levels.
## Step Packing (Author Responsibility)
Formula authors must size steps appropriately:
| Too Small | Too Large |
|-----------|-----------|
| Restart overhead dominates | Context exhaustion mid-step |
| Thrashing | Partial completion, unreliable |
**Rule of thumb**: A step should use 30-70% of available context. Batch related micro-tasks.
## The `gt mol step done` Command
Canonical way to complete a step:
```bash
gt mol step done <step-id>
```
1. Closes the step in beads
2. Finds next ready step (dependency-aware)
3. Updates hook to next step
4. Respawns pane with fresh session
**Never use `bd close` directly** - it skips the restart logic.
## Cleanup: The Finalizer Pattern
When polecat signals completion:
```
POLECAT_DONE mail → Witness creates cleanup wisp → Witness processes wisp → Burn
```
The wisp's existence IS the pending cleanup. No explicit queue.
| Cleanup Step | Verification |
|--------------|--------------|
| Git status | Must be clean |
| Unpushed commits | None allowed |
| Issue state | Closed or deferred |
| Productive work | Commits reference issue (ZFC - Witness judges) |
Failed cleanup? Leave wisp, retry next cycle.
---
## Evolution Path
Current design will evolve as model cognition improves:
| Phase | Refresh Trigger | Who Decides | Witness Load |
|-------|-----------------|-------------|--------------|
| **Now** | Step boundary | Formula (fixed) | High |
| **Spoon-feeding** | Context % + task size | Witness | Medium |
| **Self-managed** | Self-awareness | Polecat | Low |
### Now (Step-Based Restart)
- Restart every step, guaranteed
- Conservative, reliable
- `gt mol step done` handles everything
### Spoon-feeding (Future)
Requires: Claude Code exposes context usage
```
Polecat completes step
→ Witness checks: 65% context used
→ Next task estimate: 10% context
→ Decision: "send another" or "recycle"
```
Witness becomes supervisor, not babysitter.
### Self-Managed (Future)
Requires: Model cognition threshold + Gas Town patterns in training
```
Polecat completes step
→ Self-assesses: "I'm at 80%, should recycle"
→ Runs gt handoff, respawns
```
Polecats become autonomous. Witness becomes auditor.
---
## Key Commands
| Command | Effect |
|---------|--------|
| `gt mol step done <step>` | Complete step, restart for next |
| `gt mol status` | Show what's on hook |
| `gt mol progress <mol>` | Show molecule completion state |
| `gt done` | Signal POLECAT_DONE to Witness |
| `gt handoff` | Write notes, respawn (manual refresh) |