epic: non-SWE work flows without harness friction (umbrella)

[akaszubski]

Mission

Operationalize PROJECT.md's macro alignment with micro flexibility and CLAUDE.md's process applies WHEN doing software development: distinguish SWE from non-SWE work at session start, route the harness accordingly, and let the user see and override what's happening.

Single destination: When the user is doing SWE work, the harness enforces. When they are not, it stays out of the way. The system measures the difference and recalibrates without human intervention.

The disconnect being closed

PROJECT.md says macro alignment with micro flexibility; CLAUDE.md says process applies WHEN doing software development. Implementation today is the opposite: micro-rigid (every Write/Edit gated on path) and macro-blind (no upfront SWE-vs-not detection). 1,577 PreToolUse deny events Apr–May; bypass primitives (touch /tmp/skip_*, AUTONOMOUS_DEV_BYPASS=1, SKIP_AGENT_COMPLETENESS_GATE=1, --skip-review) appear in 7+ sessions.

A 13-class intent classifier (lib/intent_classifier.py, 9 SWE classes from #971 + 4 non-SWE classes from #1023) and per-session mode artifact (/tmp/session_mode_<sid>.json from Phase D #998) already exist. Phase E (#999) wired hooks to consult it — but it ships default-off. Phase 2 (#961, PR #1037) added classifier-gated plan-critic + research skip. The plumbing is built; it needs to land.

Milestones

M0 — Framework reliability (PREREQUISITE)

Without this, telemetry lies, classifier rollout is unsafe, every long pipeline is a crash risk.

• M0: Durable pipeline state isolation — per-run UUID, atomic ownership, crash-safe handoff #1041 — Durable pipeline state isolation (umbrella) — closes [CI] /tmp/implement_pipeline_state.json cleared mid-pipeline — coordinator must recreate sentinel (recurring) #989, [CI] [ORDERING-RECURRENCE] Pipeline.json cross-session leak recurred — #594 fix didn't hold, caused .bypass autocreation 2026-05-03 #1028, [CI] STEP 0 never writes issue_number to pipeline state file — agent_ordering_gate falls back incorrectly #1029, [CI] Concurrent pipeline collision on shared /tmp/implement_pipeline_state.json — no locking or per-run isolation #1030, [CI] Concurrent pipeline collision on shared /tmp/implement_pipeline_state.json — no per-run isolation #1033, [CI] completeness gate scoped to current session_id — cross-session resume always blocked at git commit #1039
• docs(claude.md): document hook deadlock protocol — surface to user, never auto-bypass #1017 — document hook deadlock protocol
• feat(security,hooks): audit + close silent agent/hook source-tree writes (Read-only spec violations) #1019 — audit & close silent agent/hook source-tree writes
• investigate: plugin symlink between autonomous-dev and consumer repos — pick canonical source-of-truth (M0) #1021 — investigate plugin symlink between autonomous-dev and consumer repos (canonical source-of-truth decision)
• fix(hooks): hook commands resolve to submodule path, not project root #1036 — hook commands resolve to submodule path, not project root
• feat(hooks): user-gated bypass mechanism — /bypass-hooks slash command + expiry, replace silent file marker #1018 — /bypass-hooks slash command (planning happens in M0; implementation lands in M3)

Exit criterion: zero /tmp/implement_pipeline_state.json collisions across 14 days; crash-resume works without manual record_agent_completion() calls.

M1 — Hook telemetry observability

Measure before tuning. Every M2/M3/M4 claim is unfalsifiable without this.

• feat(hooks,lib): per-hook timing observability (W0) #1012 — per-hook timing wrapper (W0)
• feat(observability): hook telemetry baseline — 1-day capture + p50/p95/p99 publish (M1) #1022 — 1-day baseline capture + p50/p95/p99 publish

Exit criterion: top-5 slowest hooks + top-5 most-blocked gates published; baseline JSONL committed.

M2 — Intent-aware gating: turn it on safely

This is the work. Most of the user's friction lives here.

Phase track (Phase 1 #971 + Phase D #998 + Phase E #999 already shipped):

• feat: Phase 2 — classifier-gated plan-critic + research skip #961 — Phase 2: classifier-gated plan-critic + research skip (PR feat(intent-classifier): #961 Phase 2 — classifier-gated plan-critic + research skip #1037)
• feat: Phase 3 — impact-based test selection (test_impact.py) #962 — Phase 3: impact-based test selection
• feat: Phase 4 — cross-issue research sharing (cache_key_for_files) #963 — Phase 4: cross-issue research sharing
• feat(intent): AMBIGUOUS classification → ask-once via AskUserQuestion (M2) #1024 — AMBIGUOUS → ask-once via AskUserQuestion

Hard-floor classifier wrap:

• feat(hooks): hard-floor classifier wrap — Stage 1 shadow mode (W2.1) #1014 — Stage 1 shadow mode (W2.1)
• feat(hooks): hard-floor classifier wrap — Stage 2 active enforcement (W2.2) #1015 — Stage 2 active enforcement (W2.2)

New umbrellas:

• M2: Audit every hook for classifier-gate coverage #1042 — Audit every hook for classifier-gate coverage — closes [CI] prompt-quality gate blocked implementer mid-flight causing crash — bullet threshold too tight for implement.md #1038, [CI] Spec-validator blocked by workflow enforcement when trying to write acceptance test file #931, fix(hooks): prompt drift threshold fires on multi-round single-issue remediation loops #934, [CI] doc-master fix-forward (STEP 14) blocked by prompt shrinkage — reinvocation context not set for count-fix cycles #1031, [CI] prompt_integrity hook fires on every research-skip pipeline run — systemic shrinkage pattern #1002, [CI] Coordinator blocked on READ of settings.local.json — hook write-protect fires on read operations #918, [CI] pytest-gate ordering block for docs-only deliverables forces coordinator to manually write pipeline state — no supported bypass path #913, [CI] pytest-gate ordering requirement fires on greenfield repos with no test suite #916
• M2: Calibrate non-SWE intent classes against real session corpus #1043 — Calibrate non-SWE intent classes against real session corpus

Exit criterion: INTENT_CLASSIFIER_ENFORCE=true ships as the default for doc/config/typo/status_query/conversation plus the 4 non-SWE classes from #1023; ≥80% reduction in decision=deny events on non-SWE classes; no regression on intent=implement / security_critical.

M3 — User-gated overrides

Stop silent bypasses. Make blocks visible and auditable.

• feat(hooks): user-gated bypass mechanism — /bypass-hooks slash command + expiry, replace silent file marker #1018 — /bypass-hooks <reason> slash command
• feat: --interactive / --autonomous mode flags + ask-on-second-block trigger #974 — --interactive / --autonomous mode flags + ask-on-second-block
• feat: stable named-block registry in unified_pre_tool.py + decision payload #975 — stable named-block registry (depends on feat: --interactive / --autonomous mode flags + ask-on-second-block trigger #974)
• feat: /authorize slash command for scoped per-block override (depends on #975) #976 — /authorize <block_id> scoped override (depends on feat: stable named-block registry in unified_pre_tool.py + decision payload #975)
• feat(pipeline): diff-shape-aware completeness gate (M3) #1025 — diff-shape-aware completeness gate
• feat(hooks): mode-aware agent-completeness gate (light/fix should not require full-mode agents) — #802 follow-up #1027 — mode-aware agent-completeness gate (light/fix should not require full-mode agents)
• [CI] [BYPASS] SKIP_AGENT_COMPLETENESS_GATE=1 env var silently bypasses commit gate - undocumented escape hatch #1040 — replace silent SKIP_AGENT_COMPLETENESS_GATE=1 with /authorize (today's discovery)

Exit criterion: silent .bypass file marker deprecated; every override emits a structured audit event; deletion-only diffs no longer require all 9 pipeline agents.

M4 — Self-tuning (closed-loop closer)

The actuator. Without this, "gets better every week" stays aspirational.

• feat: Phase 5 — classifier telemetry aggregation + auto-rollback #964 — Phase 5: classifier telemetry aggregation + auto-rollback
• policy: recurring-tag escalation — 3× recurrence forces root-cause review (M4) #1026 — 3× recurrence policy: forces root-cause architecture review

Exit criterion: classifier skip-rule changes ship without human approval if benchmark improves; revert if regresses; baseline updated on success.

M5 — Real-world use validation

Prove it works for what the user actually wants it to do.

• M5: One-week real-world validation in non-harness repo #1044 — One-week real-world validation in non-harness repo (realign or spektiv)

Exit criterion: ≥7 consecutive days of pipeline runs in a non-harness repo with zero manual recovery sessions and zero SKIP_AGENT_COMPLETENESS_GATE=1-class bypasses.

Dependency graph

M0 (framework reliability) ──┐
                             ├──> M2 (intent-aware gating) ──> M3 (overrides) ──> M4 (self-tuning) ──> M5 (real use)
M1 (telemetry baseline)    ──┘                                      ▲                       ▲
                                                                    │                       │
                #1042 hook audit runs in M2 ────────────────────────┘                       │
                #1043 calibration runs in M2 ─────────────────────────────────────────── ───┘

M0 and M1 can run in parallel. Everything else is strictly sequenced.

Out of scope (parallel track, not blocking)

• refactor(install): manifest reconciliation + deploy split + plugin_updater consolidation (W1) #1013 / W1 — manifest reconciliation
• refactor(lib): library audit + GenAI primitive consolidation (W3 tracker) #1016 / W3 — lib audit + GenAI primitive consolidation
• epic: Plan-critic iterative loop — Opus enforcement, multi-round orchestration, convergence detection #888 — plan-critic Tier-1 epic (separate concern)

These are internal cleanup, not on the friction critical path. They proceed in parallel.

Original empirical analysis

(Preserved from original issue body — still relevant evidence.)

Empirical analysis of 132 archived sessions over 7 days showed hooks fire on every Claude Code invocation as if it might be /implement, regardless of actual user intent. Strategic, exploratory, and triage tasks accumulated hundreds of blocks per session.

Top 8 most-blocked sessions:

Session	Prompt	Blocks
09a1e592	(local-command-caveat session)	243
e7fd9310	"bug? from other claude"	192
1bc3fea4	"what open issues do we want to work on in order of priority"	175
3c57a2ee	(local-command-caveat session)	159
44114e96	/implement #784	105
0be49a64	/implement --batch --issues 851,863,860	103
2502327a	"what open issues do we have?"	101
46261312	"look at this claude session in realign. why do i need to run critic..."	97

Sessions whose first prompt is not /implement accumulate hundreds of blocks. The classifier exists and works; it just isn't consulted at the friction-critical sites.

Current status (2026-05-04)

Milestone	Status
M0	In planning — #1041 umbrella created today
M1	Scoped — #1012, #1022 ready
M2	Phase 2 (#961) PR #1037 open; #1042 + #1043 umbrellas created today
M3	Scoped — 6 issues
M4	Scoped — #964 + #1026
M5	Scoped — #1044 umbrella created today

Next concrete move: land #1037 (Phase 2), then start M0 (#1041 + #1036).

[akaszubski]

Umbrella: Part of the semantic-aware pipeline refactor. 5-phase rollout addresses dogmatic hook firing, redundant research, and broad test runs caused by missing semantic awareness of user intent.

• Phase 1 committed in e74df72 — plugins/autonomous-dev/lib/intent_classifier.py foundation (default-off, telemetry-only)
• Phase 2 feat: Phase 2 — classifier-gated plan-critic + research skip #961 — classifier-gated plan-critic + web-research skip for non-feature intents
• Phase 3 feat: Phase 3 — impact-based test selection (test_impact.py) #962 — file-impact-based test selection (lib/test_impact.py)
• Phase 4 feat: Phase 4 — cross-issue research sharing (cache_key_for_files) #963 — cross-issue research sharing (cache_key_for_files)
• Phase 5 feat: Phase 5 — classifier telemetry aggregation + auto-rollback #964 — telemetry aggregation + auto-rollback safety net

Parent plan: ~/.claude/plans/i-also-wonder-how-snoopy-hinton.md

Status: Resolved by Phase 2 (#961). Recommend close as duplicate after #961 lands.