From bd2cd991e36874c7f531bba92f813316af0967c5 Mon Sep 17 00:00:00 2001 From: Original Gary Date: Tue, 28 Apr 2026 00:52:05 +1000 Subject: [PATCH 1/3] chore: delete .claude/rules/pipeline-nevers.md (followup) --- .claude/rules/pipeline-nevers.md | 43 -------------------------------- 1 file changed, 43 deletions(-) delete mode 100644 .claude/rules/pipeline-nevers.md diff --git a/.claude/rules/pipeline-nevers.md b/.claude/rules/pipeline-nevers.md deleted file mode 100644 index eafde48a..00000000 --- a/.claude/rules/pipeline-nevers.md +++ /dev/null @@ -1,43 +0,0 @@ -# Open Paws Pipeline — Hard Nevers - -Loaded every session (no `paths:` frontmatter). Contains the non-negotiable rules that apply to every agent, every stage, every commit, every push, in every Open Paws repo. Full 14-stage pipeline reference lives in `/pipeline-reference` skill — invoke it on demand when you need stage detail. - -## The Hard Nevers - -- **Never skip the pipeline.** No "this is a tiny fix, let's go direct to PR." Tiny fixes are the highest-risk class because nobody scrutinizes them. -- **Never fix without an issue first.** File the issue, even for "while I'm here" cleanups. No issue = no work. -- **Never use wildcard `git add`.** `git add .` / `git add -A` / `git add --all` / `git add *` collide with other agents' owned file sets and silently commit out-of-scope files. Enumerate owned files explicitly. (Enforced by the `~/.claude/hooks/block-dangerous-bash.sh` PreToolUse hook.) -- **Never write production code before tests.** RED → GREEN. Tests must be mutation-resistant. -- **Never let the desloppify strict score drop.** Score regression requires a human override label (`override:allow-score-drop`) that agents cannot apply. -- **Never use upstream desloppify.** Always `github.com/Open-Paws/desloppify` — the fork has movement conventions (no-speciesist-language, type-safety, gateway response discipline) the upstream lacks. -- **Never scope-creep mid-wave.** Adjacent bugs, refactor opportunities, test gaps → file new issues. Do not fold into the current change. -- **Never modify a test file during the implementation wave.** Test files are locked; forcing a test green is a pipeline-integrity violation. -- **Never touch files outside your declared owned set.** Subagents enforce this via `isolation: worktree` (test-writer, implementer, desloppifier); other stages enforce by discipline. -- **Never merge without adversarial clearance.** STAGE 13 runs LAST, AFTER CI+CodeQL+CodeRabbit+review subagents all green. Only a clean adversarial pass unblocks merge. -- **Never silently resolve an open decision.** If `$OP_CONTEXT_REPO/decisions.md` or `$OP_CONTEXT_REPO/proposals/` touches the proposed change, file a `[decision]` issue and block. Plans that pick a design choice without surfacing alternatives commit the org to that path invisibly. -- **Never contradict a settled decision.** `decisions.md` entries are constraints. Relitigating openly is expensive; relitigating silently via implementation is worse. File a reconsideration issue instead. -- **Never merge to `main` directly.** Branch, PR, review, merge. -- **Never share a branch between parallel agents.** Each write-stage agent runs in its own worktree. - -## Conventional Commits (required) - -Prefix every commit: `feat:` `fix:` `refactor:` `test:` `docs:` `chore:` `perf:` `ci:`. Scope matches the component label on the issue. Description is direct and real — per the voice rules in `~/.claude/CLAUDE.md`, profanity is fine when it fits; corporate filler is not. - -## Close Issues Via PR Body - -`Closes #N` in the PR body links the PR to the issue. Squash merge by default; the issue auto-closes when the PR merges. - -## Emergency Overrides (human-only) - -- `override:skip-adversarial` — requires human comment with justification -- `override:allow-score-drop` — requires human comment with numeric delta - -Agents cannot apply these labels. If an agent thinks an override is warranted, file a comment requesting human intervention and halt. - -## Context-Repo Primacy - -If context-repo guidance (`$OP_CONTEXT_REPO/decisions.md`, `priorities.md`, `org-overview.md`) conflicts with any rule or playbook, context-repo wins. This stack is HOW; the context repo is WHY. - ---- - -For the full 14-stage pipeline with wave-gate semantics, file-ownership rules, subagent definitions, and per-stage workflow: `/pipeline-reference`. From 396c6ffec9f50bb2109adda02384a838a3508ad2 Mon Sep 17 00:00:00 2001 From: Original Gary Date: Tue, 28 Apr 2026 00:52:07 +1000 Subject: [PATCH 2/3] chore: delete .claude/rules/parallelization.md (followup) --- .claude/rules/parallelization.md | 106 ------------------------------- 1 file changed, 106 deletions(-) delete mode 100644 .claude/rules/parallelization.md diff --git a/.claude/rules/parallelization.md b/.claude/rules/parallelization.md deleted file mode 100644 index 3d278be6..00000000 --- a/.claude/rules/parallelization.md +++ /dev/null @@ -1,106 +0,0 @@ -# Wave Parallelization and File Ownership - -Loaded every session. Refines the hard-nevers for concurrent agent work. Most of the file-level isolation Sam hand-rolled in earlier CLAUDE.md drafts is now handled by Claude Code's native `isolation: worktree` primitive on write-stage subagents — this file covers what the worktree primitive doesn't. - -## What Worktree Isolation Already Handles - -These subagents have `isolation: worktree` in their frontmatter and get an automatic fresh git worktree per invocation, so file-level collision between parallel instances is impossible: - -- `test-writer` (STAGE 5) -- `implementer` (STAGE 7) -- `desloppifier` (STAGE 9) - -The `.worktreeinclude` file at repo root (gitignored patterns to copy into each new worktree) handles env files, config secrets, and local state. No hand-rolled file-ownership discipline needed for these agents. - -## What Worktree Does NOT Isolate - -Shared state that lives outside the git tree stays contentious even with worktree isolation: - -- **GitHub issue comments / labels** — two agents both commenting on the same issue produce a race. Use idempotent labels (set, don't increment counters) and use comment headers to de-duplicate. -- **Branch push contention** — write-stage worktrees all push back to the same branch. Serialize pushes within a wave; a rebase-then-push pattern prevents non-fast-forward rejections. -- **External APIs** — any coalition-partner API, LLM provider, deployment target. Rate limits are shared. -- **Database migrations** — any stage touching schema runs serially, never parallel. -- **Dependency manifest changes** — `package.json`, `Cargo.toml`, `pyproject.toml`. Parallel dep bumps collide in the lockfile. -- **`.github/workflows/` edits** — workflow changes affect every repo's CI; serialize them. - -## Safe-Parallel vs Unsafe-Parallel - -| Safe to parallelize | Unsafe — serialize | -|---|---| -| Different repos, same wave | Same repo + overlapping file sets (worktree handles this for write-stages; other stages still discipline) | -| Different components in a monorepo | Migrations (DB schema) | -| Docs + code + tests (separate agents) | Dependency manifest changes | -| Read-only agents (scout, plan-reviewer, adversarial, persona-qa, verifier) | Release tagging | -| Persona QA read-only sweeps | `.github/workflows/` edits | - -## Wave Gates - -A wave is complete only when **every agent in the wave has written a completion comment** to the issue (or parent orchestration thread). The orchestrator waits for all completions before spawning the next wave. No partial advancement. - -In-progress state: issues get the `auto:in-progress` label plus an assignee representing the agent session. **TTL 4 hours of no commits → claim released automatically** by the watchdog workflow. If a wave stalls beyond TTL, the orchestrator re-dispatches to a fresh agent. - -## Branch Discipline - -One issue = one branch = one PR. Branch naming: `/-` (e.g. `fix/1234-quest-sync-silent-errors`). - -Before any write work: -```bash -git fetch origin -git checkout || git checkout -b -git pull --rebase origin -``` - -After: -```bash -git add # enforced by hook; never wildcards -git commit -m "" -git push origin -``` - -## Read-Only Agents Share the Main Tree - -Agents without `isolation: worktree` (scout, planner, plan-reviewer, test-reviewer, verifier, adversarial, persona-qa) run in the main checkout. They're read-only by design. If a read-only agent discovers it needs to write, it stops and files a new issue rather than promoting itself to a write-stage. - -## Orchestrator cwd preflight — `isolation: worktree` requires a git repo cwd - -Before dispatching any subagent with `isolation: worktree` in its frontmatter, the orchestrator MUST be in a cwd that resolves to a git repo. If cwd is outside any git repo (e.g. `$HOME`, a temp dir), the Claude Code harness can't create a fresh worktree and silently degrades to either (a) reusing a stale sibling-agent worktree or (b) operating in the main tree — both of which **break the isolation guarantee** the pipeline's wave-gate semantics rely on. - -**Preflight:** `cd "$OP_CONTEXT_REPO"` (or the relevant repo) before the first worktree-isolated dispatch in a session. Verify with `git rev-parse --show-toplevel` — error out if it returns nothing. - -This matters specifically for in-session manual orchestration. The autoagent-* GitHub Actions runners (where applicable) always invoke from inside their repo, so the problem doesn't exist there. - -## Bootstrap mode — when the pipeline taxonomy isn't wired yet - -The pipeline uses labels (`stage:triaged`, `stage:ready-for-plan`, `auto:auto-fixable`, `sensitivity:staff-ok`, etc.) as wave-gate signals — each stage watches for its trigger label on an issue. **On first pipeline run in a repo that hasn't yet had sync-labels applied**, those labels don't exist; label-driven dispatch can't fire. - -**Bootstrap-mode substitution:** each stage ends its completion comment with a short explicit sentence stating the next stage, e.g. `Advancing to STAGE 3 (plan).` The orchestrator watches for these sentences instead of labels. This is a first-run-only fallback — once sync-labels lands in a repo, the taxonomy is live and label-based dispatch resumes. - -Stage playbooks don't individually repeat this rule; they inherit it from here. If a stage's completion output in the first run doesn't include an "Advancing to STAGE N" (or "Back to STAGE N") sentence, the wave is stalled — orchestrator should re-prompt or kick back. - -Exit criteria: bootstrap mode ends when the first `sync-labels --apply` run completes in the repo. From that point the label taxonomy is the canonical signal; bootstrap-mode sentences are redundant. - -## Subagent recovery — what to do when a write-stage agent times out mid-run - -Write-stage subagents (`test-writer`, `implementer`, `desloppifier`) operate in their own worktrees at `$REPO/.claude/worktrees/agent-/` and may time out or lose connection mid-run with uncommitted work sitting in that worktree. Observed once per pipeline run as of 2026-04-24. - -**Recovery procedure** (orchestrator runs): - -1. Check the subagent's worktree state: `cd $REPO/.claude/worktrees/agent-*/ && git status --short && git log --oneline -1` -2. If uncommitted work exists: inspect the diff (`git diff`), run any tests the agent would have run to verify it's functional, then commit from the orchestrator session using the bot identity: - ```bash - git add - git -c user.name="Original Gary" -c user.email="276612211+OpenGaryBot@users.noreply.github.com" \ - commit -m ": " - git push origin - ``` - - **Always the bot identity. Never Sam's `stuckvgn` identity.** Per `~/.claude/rules/git-identity.md`. The temptation to "author under Sam so the non-last-pusher branch protection lets him self-approve" is the wrong direction — branch protection is by design, not a bug to route around. If a PR needs to merge but bot-authored commits block via non-last-pusher rule, file a `[process]` issue asking Sam to either approve or re-think the rule. Do not impersonate Sam's identity. -3. If the subagent left a stale LOCKED worktree after its branch pushed: `git worktree unlock ` then `git worktree remove -f ` to free the branch for subsequent stages. -4. Post a completion comment on the issue explaining the rescue (so adversarial and downstream stages have correct context). -5. Continue the pipeline from the next stage. - -Do NOT re-dispatch the same subagent with a fresh invocation if uncommitted work exists — you'll lose it. Rescue first, re-dispatch only if the worktree is genuinely empty. - ---- - -See `/pipeline-reference` for the full 14-stage sequence and per-stage agent assignments. From 5adcc021b90f6d873dc93eb0272b11fe061a769c Mon Sep 17 00:00:00 2001 From: Original Gary Date: Tue, 28 Apr 2026 00:52:10 +1000 Subject: [PATCH 3/3] chore: delete .claude/rules/desloppify.md (followup) --- .claude/rules/desloppify.md | 64 ------------------------------------- 1 file changed, 64 deletions(-) delete mode 100644 .claude/rules/desloppify.md diff --git a/.claude/rules/desloppify.md b/.claude/rules/desloppify.md deleted file mode 100644 index 96b64edf..00000000 --- a/.claude/rules/desloppify.md +++ /dev/null @@ -1,64 +0,0 @@ -# Code Quality — desloppify - -Run desloppify to systematically identify and fix code quality issues. Install from the **Open Paws fork** (Python 3.11+): - -```bash -# Install from this fork — NEVER from PyPI / upstream -pip install "git+https://github.com/Open-Paws/desloppify.git#egg=desloppify[full]" -desloppify update-skill claude -``` - -**Canonical install command.** This file is the single source of truth for how to install desloppify. Every other file in this stack (`skills/desloppify-playbook/SKILL.md`, `agents/desloppifier.md`, `$OP_CONTEXT_REPO/.claude/rules/desloppify.md`, every `Open-Paws/*/.claude/rules/desloppify.md`) links here rather than restating the command — duplication is how the multi-repo drift that existed pre-2026-04-25 happened. If you're editing an install command anywhere other than this file, stop. - -**OP fork only — never upstream.** The git install above pulls from `github.com/Open-Paws/desloppify`, which carries the movement conventions (no-speciesist-language rules, type-safety patterns, gateway response shape discipline, compassionate language enforcement, persona-QA browser testing) that upstream desloppify lacks. `pip install desloppify` from PyPI pulls upstream and is a hard-rule violation per `~/.claude/rules/pipeline-nevers.md`. - -Add `.desloppify/` to `.gitignore` — it contains local state that should not be committed. Before scanning, exclude generated / vendor / build dirs: - -```bash -# Exclude generated directories, then scan -desloppify exclude node_modules dist -desloppify scan --path . -``` - -`--path` is the directory to scan (use `.` for the whole project, or a subdirectory like `src/`). Your goal is to get the strict score as high as possible. The scoring resists gaming — the only way to improve it is to actually make the code better. - -## The fix loop - -Run `next` → fix → resolve → repeat: - -```bash -desloppify next # get the top-priority item; shows which file and the resolve command -# fix the code -desloppify plan resolve # mark it done -desloppify next # get the next item -``` - -It is the execution queue from the living plan, not the whole backlog. It tells you what to fix now, which file, and the resolve command to run when done. Use `desloppify backlog` only when you need to inspect broader open work not currently driving execution. - -Do not be lazy. Large refactors and small detailed fixes — do both with equal energy. No task is too big or too small. Fix things properly, not minimally. - -Use `plan` / `plan queue` to reorder priorities or cluster related issues. Rescan periodically. The scan output includes agent instructions — follow them, do not substitute your own analysis. - -## Persona-QA workflow (UI repos with persona-driven testing) - -```bash -desloppify persona-qa --prepare --url https://example.com # generate agent instructions -# agent runs browser testing and captures findings in JSON -desloppify persona-qa --import findings.json # merge into state -desloppify persona-qa --status # per-persona summary -desloppify next # persona QA items now appear in the queue -``` - -## Baseline Capture Process - -**At plan time (STAGE 3):** Capture desloppify baseline against branch point: - -```bash -desloppify status --json > .desloppify/baseline.json -``` - -Post baseline JSON as GitHub issue comment for durable storage (`.desloppify/` is gitignored). - -**Recovery if missing:** STAGE 9 uses `git merge-base HEAD main` to recapture against the branch point. - -**Score-cannot-regress gate.** STAGE 9 blocks merge if the strict score drops below baseline. Regression requires `override:allow-score-drop` label (human-only — agents cannot apply it).