feat(spec): Autocompact Config Replaces Forced-Handoff Hook

[bdfinst]

Intent Description

The plugin currently enforces its context ceiling with plugins/dev-team/hooks/context_ceiling_guard.py, a PreToolUse hook that measures transcript occupancy and, once it crosses 40% of the context window (capped at 350K, ADR 0038), blocks Skill invocations and warns on Agent dispatches until the model runs /handoff to write a structured memory/ progress file. This hook approximates a capability the Claude Code harness already owns natively: auto-compact, tunable via CLAUDE_AUTOCOMPACT_PCT_OVERRIDE (documented in ADR 0016 but never enabled by the plugin itself).

That hook-forced handoff is being replaced. Instead of a plugin-side hook forcing a handoff document, /dev-team:setup will configure the target repo's own .claude/settings.json to set the harness-native autocompact percentage directly — default 40%, project-configurable — and context_ceiling_guard.py is removed. Because this makes /setup load-bearing for a repo's context-management behavior, a lightweight, non-blocking check should recommend running /setup when a repo shows no sign it has been run.

Architecture Specification

• Remove plugins/dev-team/hooks/context_ceiling_guard.py, its registration in plugins/dev-team/settings.json, and its dedicated test file tests/hooks/test_context_ceiling_guard.py.
• /setup gains a step that writes CLAUDE_AUTOCOMPACT_PCT_OVERRIDE (the harness's own env var) into the target project's .claude/settings.json env block, defaulting to 40, with the value itself configurable (prompt or flag) rather than hardcoded. Must merge into existing env entries, not overwrite them.
• New setup-detection check: a SessionStart hook, following the existing best-effort .claude/ensure_npm_ci.py / .claude/ensure_code_graph_tools.py pattern, checks whether the project's .claude/settings.json already sets CLAUDE_AUTOCOMPACT_PCT_OVERRIDE. If absent, it prints a one-line recommendation to run /dev-team:setup. Advisory only — never blocks session start.
• /handoff skill is retained as a manually-invocable tool (continue/fork modes). Only the hook that force-triggered it is removed; it's dropped from context_ceiling_guard.py's recovery-skill allowlist because that allowlist no longer exists.
• ADR impact: this reverses ADR 0016's "harness auto-compact remains the backstop; the plugin does not lower it by default" stance, and the blocking rationale behind fix(hooks): context ceiling guard defaults to warn, so the 40% ceiling never blocks #2000. Superseding ADR 0016 (and touching ADR 0038/0039, which are guard-specific) is expected implementation work in /plan, not spec content here.
• Docs to update: docs/context-management.md, knowledge/agent-registry.md, CLAUDE.md's "Context Ceiling" principle, and any skill referencing the guard as a live mechanism (context-loading-protocol, handoff).

Acceptance Criteria

1. Running /dev-team:setup on a repo writes CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=40 (or the operator-configured value) into that repo's .claude/settings.json, without clobbering pre-existing unrelated env entries.
2. The percentage is configurable at setup time — a prompt or flag overrides the 40 default and that value is what lands in settings.json.
3. context_ceiling_guard.py, its hook registration, and its dedicated test file are deleted; no other shipped hook or skill references it as a live mechanism (historical mentions in ADRs/CHANGELOG may remain).
4. /handoff remains manually invocable and is no longer described anywhere as a hook-forced/blocked recovery path.
5. A SessionStart check detects a repo with no CLAUDE_AUTOCOMPACT_PCT_OVERRIDE in .claude/settings.json and prints a recommendation to run /dev-team:setup; it never blocks session start and never fires once the key is present.
6. The full pytest gate (scripts/ci-local.sh) passes with the guard's tests removed, and no orphaned reference trips scripts/check_md_references.py or the knowledge-index-currency check.

Ambiguity Log

Decision	Classification	Resolved By	Rationale / Answer
What happens to context_ceiling_guard.py's blocking behavior (kept as warn-only vs. removed entirely)	requires-stakeholder-input	human	Remove the hook entirely — rely solely on harness-native autocompact, no plugin-side context signal.
Whether this supersedes ADR 0016 / #2000's data-backed blocking rationale (76+ sessions ran past 500K under warn-only, 18 past 900K)	requires-stakeholder-input	human	Yes — explicit in the request. An ADR superseding 0016 is implementation work for /plan, not this spec.
Configuration mechanism for the percentage	inferable	inference	Matches the plugin's existing DEV_TEAM_*-style env-knob convention and the harness's own already-documented CLAUDE_AUTOCOMPACT_PCT_OVERRIDE (ADR 0016); no other knob exists for this today.
Setup-detection signal and hook type	inferable	inference	Matches the existing SessionStart "ensure_*" best-effort pattern already in the project (ensure_npm_ci.py, ensure_code_graph_tools.py); presence of the settings.json key is the natural completion signal.
Whether /handoff the skill is removed or just its forced trigger	inferable	inference	The request targets "the hook to force it," not the skill itself; manual /handoff still has value for fork mode and deliberate summarization independent of the ceiling.
Whether the guard's 350K absolute cap (ADR 0038) carries over	inferable	inference	The harness's CLAUDE_AUTOCOMPACT_PCT_OVERRIDE is percentage-only with no absolute-cap concept; dropped along with the hook rather than reimplemented.

Consistency Gate

• Intent is unambiguous
• Every behavior/goal maps to an acceptance criterion
• Architecture constrains without over-engineering
• Terminology consistent across artifacts
• No contradictions between artifacts
• Every gap/ambiguity finding is logged — inferable with rationale or resolved by human

🤖 Generated with Claude Code