1 added, 1 removed. Audit A to A.
# autonomous-dev
Development harness for Claude Code. Deterministic enforcement, specialist agents, alignment gates — 12 elements of harness engineering.
- **Active goal**: [GOAL_2026-08-24_enforcement-proven-everywhere](docs/experiments/GOAL_2026-08-24_enforcement-proven-everywhere.md) — every shipped guard proven refusing AND permitting, in every repo it reaches. Baseline: 4 of 8 guards fail open silently here; 0 proof artifacts in realign or spektiv. Mid-point abort check 2026-09-07.
+ **Active goal**: [GOAL_2026-08-24_enforcement-proven-everywhere](docs/experiments/GOAL_2026-08-24_enforcement-proven-everywhere.md) — every shipped guard proven refusing AND permitting, in every repo it reaches. Baseline: 4 of 8 guards fail open silently here; 0 proof artifacts in realign or spektiv. **v4 re-baseline 2026-08-28: 1 slip on the board — one more aborts (§7.5). Mid-point abort check moved to 2026-09-09.** Standing rule (§2): **a finding that can refuse becomes a guard, not an issue** — filing is running 4.5× ahead of resolving (114 opened / 25 closed in 7 days, 290 open), and net-positive issue delta over 7 days is now itself an abort condition (§7.6).
For purpose, scope, and architecture see [`.claude/PROJECT.md`](.claude/PROJECT.md). For operational sequences (build, test, deploy, periodic maintenance) see [`docs/RUNBOOK.md`](docs/RUNBOOK.md). For where content lives (the content allocation pattern dogfooded here) see [`docs/development/CONTENT_ALLOCATION.md`](docs/development/CONTENT_ALLOCATION.md).
## Critical Rules
- **`.claude/PROJECT.md` sets direction — check work against it before starting.** A clash stops the work, or changes the file with the tradeoff argued and agreed against project intent — never both silently, never assumed. It is *intent*, not description: where the code differs, the code is the defect. Its gate has never refused anything (#1639), so the check is currently yours to make.
- **NEVER direct-edit without `/implement`**: `agents/*.md`, `commands/*.md`, `hooks/*.py`, `lib/*.py`, `skills/*/SKILL.md` — these are functional infrastructure. Hook-enforced: `unified_pre_tool.py` blocks Write/Edit to these paths outside the pipeline. Issue #1296 adds agent-dispatch sentinel tracking — coordinators cannot directly edit these paths mid-pipeline even inside `/implement`; they must re-dispatch the implementer agent.
- **Direct editing is only for**: user-facing docs (README.md, CHANGELOG.md, docs/*.md), editor/lint config files that do NOT drive deployment or enforcement (.editorconfig, pyproject.toml lint sections, .gitignore), and typos (1–2 lines). Deployment manifests (install_manifest.json), policy files (auto_approve_policy.json, hard_floor_hooks.json, sandbox_policy.json), and settings templates (templates/settings.*.json) require `/implement`.
- **After plan mode approval → use `/implement`**: The plan IS the input to `/implement`, not a license to bypass it.
- **P0 fixes on production code require at minimum `/implement --fix` mode** (implementer + reviewer + doc-master + CIA) — never call implementer alone.
- **Run `/improve` after `/implement` sessions.** Use `--auto-file` to create GitHub issues.
- **Deploy with `bash scripts/deploy-all.sh`** — never manual `cp -rf`. Script handles local, remote (Mac Studio), validation, and integrity checks.
- **Don't collapse the specialist agents to save tokens.** Fresh context per specialist (INV-2) is the mechanism, and its cost is tokens — that trade is deliberate. This protects the *agent roster and pipeline shape* (INV-3) only. It is **not** a licence for complexity anywhere else: hooks, `lib/`, and enforcement are subject to PROJECT.md's minimalism gate like all other code, and a control nobody can reason about is not a control. Narrowed 2026-08-25 — the previous wording ("complexity is the mechanism", covering hooks and enforcement) contradicted PROJECT.md's "Less is more" and licensed a 9,170-line hook file holding **51 checks** behind one 5s timeout — the count is MEASURED in [`docs/audits/unified-pre-tool-51-check-audit.md`](docs/audits/unified-pre-tool-51-check-audit.md) (2026-08-21, three parallel audits) and carried by #1631. An earlier revision of this line said "30 checks" with no source; that figure was unprovenanced and is withdrawn.
## Maintainer Escape Hatches
When working **on autonomous-dev itself**, the hook stack can occasionally deadlock — a `/implement` run leaves stuck state, the state-deletion guard (#803) blocks cleanup, and the documented env-var bypasses (`PIPELINE_CLEANUP_PHASE=1`, `ENFORCEMENT_LEVEL=off`, `SKIP_AGENT_COMPLETENESS_GATE=1`) don't propagate to hook subprocesses mid-session (Issue #779). Two file-based mechanisms work mid-session:
| Marker | Scope | Use when |
|---|---|---|
| `.claude/.bypass` | **Universal** — disables ALL hooks for any session whose cwd is in this directory tree (walks up 30 levels), **except the protected-infrastructure hard floor** (Issue #1435): a direct write via **any write-classified tool** (Write, Edit, MultiEdit, NotebookEdit, or an MCP editor such as `mcp__serena__replace_symbol_body` — classification is `tool_intent.is_write()`, Issue #1503) to `agents/*.md`, `commands/*.md`, `hooks/*.py`, `lib/*.py`, `skills/*/SKILL.md` inside the canonical autonomous-dev source stays blocked even under bypass — use `/implement` for those edits. | (1) **Emergency**: disables test/security/docs and workflow gates (but NOT the #1435 protected-infra hard floor — that requires `/implement`). Remove (`rm .claude/.bypass`) as soon as the immediate blocker is past — an **uncommitted** `.claude/.bypass` older than 24h (override: `AUTONOMOUS_DEV_BYPASS_STALE_HOURS`) now emits a loud staleness WARNING at session start (Issue #1434), so a forgotten emergency bypass can't silently disable enforcement for days. (2) **Durable per-repo opt-out**: consumer repos that do not want autonomous-dev SDLC enforcement can commit `.claude/.bypass` permanently — this is the supported way to opt out of the default-on production-code Write/Edit gate (Phase 1, Issue #1142+). Exception: in self-maintenance mode (canonical autonomous-dev source), `git commit` invocations still pass through the agent-completeness gate (#1195) — to skip that specific gate use `SKIP_AGENT_COMPLETENESS_GATE`. |
| Self-maintenance mode (auto) | **Targeted** — relaxes only state-deletion (#803) when cwd is inside the canonical autonomous-dev source (detected by `plugins/autonomous-dev/.claude-plugin/marketplace.json`) | Automatic. No action needed. Other gates (test, security, doc-master, prompt-integrity, workflow-enforcement) remain enforced — dogfooding is preserved. |
| `SKIP_AGENT_COMPLETENESS_GATE` (Issue #1040) | **Narrow** — bypasses only the agent-completeness gate at `git commit` time (Issues #802, #853) when required pipeline agents (`reviewer`, `security-auditor`, `doc-master`, `continuous-improvement-analyst`) have not all completed. Three forms, in reliability order: (1) `touch /tmp/skip_agent_completeness_gate` as a SEPARATE Bash command first, then retry — file-based one-shot, consumed on first check, works mid-session; (2) `SKIP_AGENT_COMPLETENESS_GATE=1 git commit ...` inline command-string prefix — the hook parses the Bash command string for the env-var prefix (case-insensitive); (3) `export SKIP_AGENT_COMPLETENESS_GATE=1` BEFORE launching claude (env vars do NOT propagate mid-session — the hook runs in a separate process; Issue #779). | Emergencies only — for example, hotfixes outside the normal pipeline flow (CI workflow tweaks, README fixes, urgent production patches). Each bypass is logged to `.claude/logs/activity/<date>.jsonl` with a specific `bypass: ...` reason string (file, inline, env), so auditors can distinguish legitimate skips from gaming. The preferred path for legitimate skips is `record_agent_completion()` for the absent agents (satisfies the gate without bypass). If you find yourself reaching for this bypass more than a couple of times per cycle, file an issue — the gate is mis-scoped. |
Self-maintenance mode is the routine path for autonomous-dev itself; `.claude/.bypass` is the universal escape hatch (emergency kill, or durable per-repo opt-out). The Phase 1 polarity flip (Issue #1142+) replaced the previous `.claude/.enforce` opt-IN marker with default-ON enforcement subject to `.claude/.bypass` opt-out. If you reach for `.claude/.bypass` as an *emergency* more than once in a blue moon, file an issue — targeted relaxation should grow to cover the case instead.
## Architecture
- **Pipeline**: 8-step SDLC — alignment → research → plan → acceptance tests → implement → validate → verify → git
- **Enforcement**: hooks returning JSON `{"decision": "block"}`. A gate declared only in prose is not enforcement (INV-1) — and several currently are (#1637, #1608).
- **Agents**: specialists with fresh context per invocation, model-tiered
- **Skills**: domain packages, progressively injected per-step to prevent context bloat
Counts, diagram and layer breakdown: [`docs/ARCHITECTURE-OVERVIEW.md`](docs/ARCHITECTURE-OVERVIEW.md) — the single home for volatile detail (PROJECT.md ARCHITECTURE). Do not restate counts here; two homes is how they drift.
## Code Navigation
Serena LSP is configured here (`.mcp.json`, #1451) — the global "Serena for dependencies, grep for strings" rule applies. Repo-specific: dead-code detection feeds `/refactor --code` and `/sweep`. The hook loads `lib/` via `importlib`, which LSP cannot follow, so hook call sites need grep and the disagreement must be named, not silently resolved.
## Commands
`/plan` | `/implement` (full, --light, --batch, --issues, --resume, --fix) | `/create-issue` (--quick) | `/plan-to-issues` (--quick) | `/align` (--project, --docs, --retrofit, --content) | `/audit` (--quick, --security, --docs, --code, --tests) | `/setup` | `/sync` (--github, --env, --all, --uninstall) | `/health-check` | `/advise` | `/worktree` (--list, --status, --merge, --discard) | `/scaffold-genai-uat` | `/status` | `/refactor` (--tests, --docs, --docs-redundancy, --code, --fix, --quick) | `/sweep` | `/improve` (--auto-file) | `/retrospective` | `/mem-search` | `/skill-eval` (--quick, --skill, --update) | `/autoresearch` (--target, --metric, --iterations, --min-improvement, --dry-run) | `/triage` (--auto-improvement, --repo, --limit, --include-fp-acknowledged, --json) | `/drain-queue` | `/goa` (start, stop, status)
User-facing reference: [`plugins/autonomous-dev/docs/COMMANDS.md`](plugins/autonomous-dev/docs/COMMANDS.md). Source of truth: `plugins/autonomous-dev/commands/<name>.md`.
## Key Paths
| What | Where |
|------|-------|
| Alignment source of truth | [.claude/PROJECT.md](.claude/PROJECT.md) |
| Content allocation rules | [docs/development/CONTENT_ALLOCATION.md](docs/development/CONTENT_ALLOCATION.md) |
| Operational runbook | [docs/RUNBOOK.md](docs/RUNBOOK.md) |
| Pipeline command | `plugins/autonomous-dev/commands/implement.md` |
| State machine | `plugins/autonomous-dev/lib/pipeline_state.py` |
| Hook enforcement | `plugins/autonomous-dev/hooks/unified_pre_tool.py` |
| Agent definitions | `plugins/autonomous-dev/agents/` |
| Test suite | `tests/` (unit, integration, regression, security, hooks, genai) |
| Activity logs | `.claude/logs/activity/` |
| Architecture details | [docs/ARCHITECTURE-OVERVIEW.md](docs/ARCHITECTURE-OVERVIEW.md) |
| Troubleshooting | [plugins/autonomous-dev/docs/TROUBLESHOOTING.md](plugins/autonomous-dev/docs/TROUBLESHOOTING.md) |
## Session Continuity
Restored by `SessionStart-batch-recovery.sh` after `/clear` or auto-compact; activity in `.claude/logs/activity/`. Archive schema and queries: global `~/.claude/CLAUDE.md` and [`docs/SESSION-ANALYTICS.md`](docs/SESSION-ANALYTICS.md).
**`.claude/` is gitignored** (`.gitignore:147`) — plans, findings and validator verdicts written there do not survive a clone (#1634). Anything durable goes to an issue, a commit message, or `docs/`.
**Last Updated**: 2026-05-27