Context
Project CLAUDE.md has been growing unbounded in the Pinned Context section. As of 2026-04-20 it hit 43.4k chars (warning threshold 40k), with 23 pins averaging 1,254 chars — total ~29k chars just in the pinned block. The soft ~1200 token budget warning comment in staleness.py has been ignored for weeks because it has no teeth.
A manual curation pass on 2026-04-20 reduced the section to 12 pins × ≤1500 chars (with one override). This issue tracks making the cap structural.
Proposed Enforcement Shape
-
/PACT:pin-memory refuses add when:
- current pin count == 12 (cap), OR
- new pin body > 1500 chars
...unless the pin has a <!-- pin-size-override: {rationale} --> comment.
-
Refusal returns a decision prompt: "Evict which existing pin? [numbered list of current pins] / Or split this pin? / Or archive to pact-memory only?"
-
SessionStart staleness check gains a hard rule: ≥2 pins flagged STALE → block session start until orchestrator confirms archive/retain (current behavior just decorates with <!-- STALE: ... -->).
-
Orchestrator instructions surface pin-slot count in context (e.g., "11/12 pin slots used, 340 chars remaining on largest pin"). Helps orchestrator self-calibrate before attempting add.
Override escape hatch
Some pins legitimately exceed 1500 chars because the verbatim text is load-bearing for LLM readers (agents need to read the exact string, not a paraphrase). The canonical `Task()` dispatch form is the current example. Override syntax:
```markdown
Canonical Task() dispatch is mirrored inline at every consumer site
...
```
Rule: override rationale is required, visible in markup, and surfaces in the pin-memory command audit.
Acceptance Criteria
Implementation Notes
Touches:
- `pact-plugin/commands/pin-memory.md` — add-time gates
- `pact-plugin/hooks/staleness.py` — hard block on ≥2 stale
- `pact-plugin/hooks/shared/claude_md_manager.py` — override comment parser + slot-count surfacing
- `pact-plugin/hooks/session_init.py` — inject pin-slot count into orchestrator context
Variety Assessment
Estimated variety: ~9 (hook_infrastructure + user-facing-protocol-changes). Per institutional calibration prior (+6 floor for this domain, evidenced by PR #454, #457, #477), plan for effective variety ~15 with 4-6 remediation cycles. Plan-mode recommended before orchestrate to avoid mid-implementation scope creep — particularly around the override comment syntax and eviction prompt UX.
Related
Context
Project CLAUDE.md has been growing unbounded in the Pinned Context section. As of 2026-04-20 it hit 43.4k chars (warning threshold 40k), with 23 pins averaging 1,254 chars — total ~29k chars just in the pinned block. The soft
~1200 token budgetwarning comment instaleness.pyhas been ignored for weeks because it has no teeth.A manual curation pass on 2026-04-20 reduced the section to 12 pins × ≤1500 chars (with one override). This issue tracks making the cap structural.
Proposed Enforcement Shape
/PACT:pin-memoryrefuses add when:...unless the pin has a
<!-- pin-size-override: {rationale} -->comment.Refusal returns a decision prompt: "Evict which existing pin? [numbered list of current pins] / Or split this pin? / Or archive to pact-memory only?"
SessionStart staleness check gains a hard rule: ≥2 pins flagged
STALE→ block session start until orchestrator confirms archive/retain (current behavior just decorates with<!-- STALE: ... -->).Orchestrator instructions surface pin-slot count in context (e.g., "11/12 pin slots used, 340 chars remaining on largest pin"). Helps orchestrator self-calibrate before attempting add.
Override escape hatch
Some pins legitimately exceed 1500 chars because the verbatim text is load-bearing for LLM readers (agents need to read the exact string, not a paraphrase). The canonical `Task()` dispatch form is the current example. Override syntax:
```markdown
Canonical Task() dispatch is mirrored inline at every consumer site
...
```
Rule: override rationale is required, visible in markup, and surfaces in the pin-memory command audit.
Acceptance Criteria
Implementation Notes
Touches:
Variety Assessment
Estimated variety: ~9 (hook_infrastructure + user-facing-protocol-changes). Per institutional calibration prior (+6 floor for this domain, evidenced by PR #454, #457, #477), plan for effective variety ~15 with 4-6 remediation cycles. Plan-mode recommended before orchestrate to avoid mid-implementation scope creep — particularly around the override comment syntax and eviction prompt UX.
Related