refactor(mcp): flatten Handler god-object, promote session state to entity

Closes TASKS.md:45 ("Move 6 grandfathered cross-package MCP types to
entity/") by eliminating the Handler struct entirely and reducing the
grandfathered cross-package types count from 6 to 0.

## Phase 1 — sub-task moves

- `def/prompt.EntrySpec`/`EntryField` -> `entity.PromptEntrySpec`/
  `PromptEntryField` (pure data, natural entity fit)
- `internal/mcp/session/*` collapsed into `internal/mcp/handler/*`
  (sole consumer; eliminates the sibling crossing)
- `internal/mcp/server/poll/` -> `internal/mcp/server/dispatch/poll/`
  (ancestor->descendant exemption closes the last sibling crossing
  before Phase 2)

## Phase 2 — flatten the Handler god-object

The Handler struct was a parameter bundle masquerading as domain
logic. 13 of its 17 methods only read ContextDir; 2 mutated session
state; the other 2 did not touch the receiver at all. TokenBudget
was a pass-through passenger consumed only by dispatch.go.

- New `entity.MCPDeps { ContextDir, TokenBudget, *MCPSession }`
  parameter object, held by the server and threaded through dispatch
- New `entity.MCPSession` holding the former session.State fields
  with pure Record*/Increment* mutation methods (no I/O)
- New `entity.PendingUpdate` (pure data)
- All 17 `(h *Handler) Foo(...)` methods converted to free functions
  `handler.Foo(d *entity.MCPDeps, ...)`
- `handler.CheckGovernance` kept as a free function in handler/
  because it still reads .context/state/violations.json (Phase 3
  absorbed into Phase 2 naturally)
- `server.Server.handler *handler.Handler` replaced with
  `server.Server.deps *entity.MCPDeps`; route/tool/* and
  route/prompt/* updated to take `*entity.MCPDeps`
- `handler.Handler` struct deleted entirely; `handler/handler.go`
  deleted; `handler/state.go` deleted
- `governance_test.go` rewritten to construct `*entity.MCPDeps`

## Grandfather purge (TestTypeFileConvention)

The grandfatheredTypes map was cleared to zero entries. All 35
underlying violations across 18 packages were fixed by moving type
declarations into per-package types.go files; methods remain in
their original files, which become type-decl-free and are skipped
by the audit.

- New types.go created in 13 packages (cli/dep/core/{golang,node,
  python,rust}, cli/drift/core/{fix,out}, cli/guide/core/skill,
  cli/remind/core/store, cli/system/core/nudge, cli/why/core/data,
  config/memory, mcp/server/catalog, mcp/server/io)
- fm.go renamed to types.go (frontmatter) and atom.go renamed to
  types.go (rss) since they were pure type definition files
- session.go regenerated with only the Session interface
- parser.{ClaudeCode,Copilot,CopilotCLI,MarkdownSession} and
  lookup.commandEntry absorbed into their packages' existing types.go

Hardened the grandfatheredTypes comment with an explicit agent
directive: do not add entries here under any circumstance. Any
re-addition requires a dedicated pull request with per-entry
justification and maintainer approval. Drive-by additions by any
assistant are unauthorized.

## Interface segregation

Interfaces are behavioral contracts, not data blueprints, so they
live in their own <name>.go files rather than types.go.

- TestTypeFileConvention updated: interface type declarations are
  now exempt from the "must have exported receiver" phase 4 check.
  Interfaces cannot carry receivers; a file containing only an
  interface is a valid pure type file.
- `parser.Session` interface moved to journal/parser/session.go
- `builder.GraphBuilder` interface moved to
  cli/dep/core/builder/graph_builder.go

## Audit state

- TestCrossPackageTypes: grandfathered 6 -> 0
- TestTypeFileConvention: grandfathered map 34 -> 0
- TestDocCommentStructure: 0 (unchanged)
- make test: all pass
- make lint: 0 issues

## Documentation

Updated .context/DETAILED_DESIGN-mcp.md, .context/ARCHITECTURE.md,
.context/DANGER-ZONES.md, and .context/DETAILED_DESIGN.md to reflect
the new package layout (no more mcp/session, poll lives under
dispatch, Handler replaced by entity.MCPDeps).

Also sweeps in two pre-existing .context/ entries that were
uncommitted at session start (architecture skill pipeline decision,
pad index shifting learning).

Spec: specs/mcp-handler-flatten.md

Signed-off-by: Jose Alekhinne <jose@ctx.ist>

Author: josealekhine

.context/ARCHITECTURE.md

@@ -91,7 +91,6 @@ graph TD
 
     MCP --> HANDLER[mcp/handler]
     MCP --> PROTO[mcp/proto]
-    MCP --> SESSION[mcp/session]
     HANDLER --> DOMAIN
 
     CORE --> DOMAIN[domain packages]
@@ -163,12 +162,12 @@ graph TD
 | `mcp/proto` | JSON-RPC 2.0 message types, MCP constants |
 | `mcp/server` | Main loop: stdin read, dispatch, stdout write |
 | `mcp/server/dispatch` | Method-based request routing |
+| `mcp/server/dispatch/poll` | File mtime polling for change notifications |
 | `mcp/server/catalog` | URI-to-file resource mapping (9 resources) |
-| `mcp/server/poll` | File mtime polling for change notifications |
 | `mcp/server/route/*` | Handlers: initialize, ping, tool, prompt, resource |
 | `mcp/server/def/*` | Tool (11) and prompt (5) definitions |
-| `mcp/handler` | Domain logic (testable without JSON-RPC) |
-| `mcp/session` | Per-session advisory state and governance |
+| `mcp/handler` | Domain logic as free functions taking `*entity.MCPDeps` |
+| `entity.MCPSession` | Per-session advisory state (pure data + mutations) |
 
 ### CLI Commands (`internal/cli/*`)
 

.context/DANGER-ZONES.md

@@ -25,8 +25,8 @@ Enriched 2026-04-03 via GitNexus (blast radius verified)._
 | journal/parser | 1MB buffer limit | MEDIUM | n/a | n/a | Large tool results truncated without warning |
 | memory | Slug format dependency | MEDIUM | 7 | 7 | Claude Code naming convention change breaks discovery |
 | drift | Path ref false positives | MEDIUM | n/a | n/a | Code examples in markdown trigger false warnings |
-| mcp/server/poll | Mtime granularity | MEDIUM | n/a | n/a | Sub-second changes between polls are missed |
-| mcp/session | In-memory only state | MEDIUM | n/a | n/a | Server restart loses governance tracking |
+| mcp/server/dispatch/poll | Mtime granularity | MEDIUM | n/a | n/a | Sub-second changes between polls are missed |
+| entity.MCPSession | In-memory only state | MEDIUM | n/a | n/a | Server restart loses governance tracking |
 | mcp/handler | Fuzzy task matching | MEDIUM | n/a | n/a | Word overlap threshold (2) causes false positives |
 | rc | sync.Once lock-in | MEDIUM | n/a | n/a | First RC() call locks config for process lifetime |
 | bootstrap | PersistentPreRunE | MEDIUM | n/a | n/a | New commands without SkipInit fail pre-.context/ |
@@ -41,7 +41,7 @@ Enriched 2026-04-03 via GitNexus (blast radius verified)._
    layer: MCP handler (all 11 tool methods), format (TimeAgo,
    Duration, Tokens), index (GenerateTable, UpdateDecisions,
    UpdateLearnings), tidy, trace, memory, sysinfo, io (SafeFprintf),
-   mcp/session (CheckGovernance), mcp/server (Serve).
+   mcp/handler (CheckGovernance), mcp/server (Serve).
    Participates in 53 execution flows.
    - Blast radius: d=1: 30+, flows: 53
    - Risk: CRITICAL (enriched 2026-04-03 via GitNexus)
@@ -165,12 +165,14 @@ Enriched 2026-04-03 via GitNexus (blast radius verified)._
    between polls are coalesced.
    - Risk: MEDIUM
 
-### internal/mcp/session
+### entity.MCPSession / mcp/handler CheckGovernance
 
 1. **In-memory only state** - Session governance lost on restart.
-   CheckGovernance has clean call chain (d=1: 1 -> appendGovernance
-   -> DispatchCall -> Do) but the advisory data it tracks is
-   ephemeral.
+   `handler.CheckGovernance` has clean call chain (d=1: 1 ->
+   appendGovernance -> DispatchCall -> Do) but the advisory data
+   it tracks is ephemeral. Data lives in `entity.MCPSession`;
+   the I/O-touching CheckGovernance free function lives in
+   `mcp/handler` because it drains `.context/state/violations.json`.
    - Blast radius: d=1: 1, d=2: 1, d=3: 1 (clean chain)
    - Risk: MEDIUM (enriched 2026-04-03 via GitNexus)
 

.context/DECISIONS.md

@@ -3,6 +3,7 @@
 <!-- INDEX:START -->
 | Date | Decision |
 |----|--------|
+| 2026-04-09 | Architecture skill pipeline is a triad not a quartet |
 | 2026-04-08 | Remove #done tag convention, simplify task archival |
 | 2026-04-06 | Use hook relay for session provenance instead of JSONL parsing or env vars |
 | 2026-04-04 | TestNoMagicStrings and TestNoMagicValues no longer exempt const/var definitions outside config/ |
@@ -118,6 +119,20 @@ For significant decisions:
 
 -->
 
+## [2026-04-09-001332] Architecture skill pipeline is a triad not a quartet
+
+**Status**: Accepted
+
+**Context**: Had a proposed ctx-architecture-extend for extension point mapping, making four skills
+
+**Decision**: Architecture skill pipeline is a triad not a quartet
+
+**Rationale**: Extension points already covered per-module in DETAILED_DESIGN and by registration site discovery in enrich. Fourth skill fragments pipeline without distinct value
+
+**Consequence**: Pipeline is map enrich hunt. Three skills three questions: how does it work, how well does it connect, where will it break
+
+---
+
 ## [2026-04-08-013731] Remove #done tag convention, simplify task archival
 
 **Status**: Accepted

.context/DETAILED_DESIGN-mcp.md

@@ -1,6 +1,6 @@
 # Detailed Design: MCP Server
 
-Modules: mcp/proto, mcp/handler, mcp/server/*, mcp/session
+Modules: mcp/proto, mcp/handler, mcp/server/*
 
 ## Overview
 
@@ -54,7 +54,7 @@ dispatch, writes responses to stdout.
 **Key types**:
 ```
 Server {
-    handler      *handler.Handler
+    deps         *entity.MCPDeps   // ContextDir, TokenBudget, Session
     version      string
     out          *mcpIO.Writer     // mutex-protected stdout
     in           io.Reader         // stdin
@@ -85,10 +85,13 @@ URI-to-file resource mapping. 9 resources: 8 individual context
 files + 1 assembled agent packet (`ctx://context/agent`).
 `Init()` builds lookup map once; `ToList()` returns immutable list.
 
-### server/poll
+### server/dispatch/poll
 File mtime-based polling (5s interval). Lazy goroutine lifecycle:
 starts on first Subscribe(), stops when all unsubscribed.
-Emits `notifications/resources/updated` via callback.
+Emits `notifications/resources/updated` via callback. Lives as a
+descendant of `server/dispatch` so both server (ancestor) and
+dispatch (parent) can consume `Poller` without triggering the
+sibling cross-package-type check.
 
 ### server/route/*
 Method-specific handlers:
@@ -152,36 +155,48 @@ Lightweight analytics: `TotalAdds(m)` sums entry add counts.
 - Consider concurrent tool execution for read-only tools
 - Resource change detection could use fsnotify instead of polling
 
-**Dependencies**: handler, proto, session, config/mcp/*
+**Dependencies**: handler, proto, entity, config/mcp/*
 
 ---
 
 ## mcp/handler
 
 **Purpose**: Domain logic implementation, testable without JSON-RPC
-coupling. All tool and prompt functionality lives here.
+coupling. All tool and prompt functionality lives here as free
+functions that take a `*entity.MCPDeps` as the first argument.
 
-**Key types**:
+**Runtime bundle** (defined in `entity/mcp_deps.go`):
 ```
-Handler {
+MCPDeps {
     ContextDir  string
     TokenBudget int
-    Session     *session.State
+    Session     *entity.MCPSession
 }
 ```
 
-**Exported API**:
-- `Status()`: context health summary
-- `Add(type, content, opts)`: validate boundary, write entry
-- `Complete(query)`: mark task done by number/text match
-- `Drift()`: detect violations/warnings
-- `Recall(limit, since)`: query session history
-- `WatchUpdate(type, content, opts)`: write + queue pending update
-- `Compact(archive)`: move completed tasks to archive
-- `Next()`: next pending task
-- `CheckTaskCompletion(recentAction)`: match action to tasks
-- `SessionEvent(eventType, caller)`: start/end lifecycle
-- `Remind()`: list pending reminders
+The server holds a single `*MCPDeps`, threaded through
+dispatch into each handler function.
+
+**Exported API** (all free functions — no receiver):
+- `Status(d)`: context health summary
+- `Add(d, type, content, opts)`: validate boundary, write entry
+- `Complete(d, query)`: mark task done by number/text match
+- `Drift(d)`: detect violations/warnings
+- `Recall(d, limit, since)`: query session history
+- `WatchUpdate(d, type, content, opts)`: write + queue pending update
+- `Compact(d, archive)`: move completed tasks to archive
+- `Next(d)`: next pending task
+- `CheckTaskCompletion(d, recentAction)`: match action to tasks
+- `SessionEvent(d, eventType, caller)`: start/end lifecycle
+- `Remind(d)`: list pending reminders
+- `SteeringGet(d, prompt)`: applicable steering files
+- `Search(d, query)`: full-text search across context files
+- `SessionStartHooks(d)` / `SessionEndHooks(d, summary)`:
+  run session-lifecycle triggers
+- `CheckGovernance(d, toolName)`: compute advisory warnings
+  for the current tool response (does violations-file I/O,
+  which is why it stays in `handler/` rather than being a
+  method on `entity.MCPSession`)
 
 ### handler/task
 Task list parsing for MCP: `ForEachPending(lines, fn)` iterates
@@ -201,32 +216,51 @@ entity, io, rc
 
 ---
 
-## mcp/session
+## entity.MCPSession
 
-**Purpose**: Per-session advisory state and governance warnings.
+**Purpose**: Per-MCP-run advisory state. Lives in `internal/entity/`
+because it is pure data + pure mutation methods, with no I/O.
+Formerly the `mcp/session.State` type; promoted to entity when
+the `mcp/session` package was collapsed into `mcp/handler` and
+the god-object Handler was dissolved.
 
-**Key types**:
+**Key type**:
 ```
-State {
+MCPSession {
     ToolCalls        int
     AddsPerformed    map[string]int
+    SessionStartedAt time.Time
     PendingFlush     []PendingUpdate
-    sessionStarted   bool
-    contextLoaded    bool
-    lastDriftCheck   time.Time
-    callsSinceWrite  int
+    SessionStarted   bool
+    ContextLoaded    bool
+    LastDriftCheck   time.Time
+    LastContextWrite time.Time
+    CallsSinceWrite  int
 }
 ```
 
-**Governance warnings** (appended to tool responses):
-1. Session not started (if sessionStarted=false)
-2. Context not loaded (if contextLoaded=false)
+**Pure methods** (all in `entity/mcp_session.go`):
+- `NewMCPSession() *MCPSession`
+- `RecordToolCall()`, `RecordAdd(type)`
+- `QueuePendingUpdate(u)`, `PendingCount()`
+- `RecordSessionStart()`, `RecordContextLoaded()`
+- `RecordDriftCheck()`, `RecordContextWrite()`
+- `IncrementCallsSinceWrite()`
+
+**Governance warnings** (computed by `handler.CheckGovernance`,
+which lives in `mcp/handler` because it does I/O on the
+violations file):
+1. Session not started (if SessionStarted=false)
+2. Context not loaded (if ContextLoaded=false)
 3. Drift not checked (after interval or min calls)
-4. Persist nudge (after callsSinceWrite threshold)
-5. Violations from extension (reads violations.json)
+4. Persist nudge (after CallsSinceWrite threshold)
+5. Violations from extension (reads violations.json — the one
+   bit of I/O that forced splitting CheckGovernance out of the
+   entity-side methods)
 
-**Data flow**: Each tool call -> RecordToolCall() ->
-CheckGovernance() -> warnings appended to response text.
+**Data flow**: Each tool call -> `d.Session.RecordToolCall()` ->
+`handler.CheckGovernance(d, toolName)` -> warnings appended to
+response text.
 
 **Edge cases**:
 - violations.json is read-and-cleared (one-shot delivery)
@@ -239,10 +273,12 @@ CheckGovernance() -> warnings appended to response text.
    config/mcp/governance — not user-configurable.
 
 **Extension points**:
-- Add new governance rules in CheckGovernance()
+- Add new governance rules in `handler.CheckGovernance`
 - Violations file format is extensible
 
-**Dependencies**: config/mcp/governance, proto
+**Dependencies**: time (entity side); config/mcp/governance,
+proto, assets/read/desc, config/format, config/token,
+config/mcp/tool (handler side)
 
 ---
 

.context/DETAILED_DESIGN.md

@@ -8,7 +8,7 @@ edge cases, danger zones, extension points).
 |--------|------|---------|---------|
 | Foundation | [DETAILED_DESIGN-foundation.md](DETAILED_DESIGN-foundation.md) | config/*, assets/*, io, format, parse, sanitize, validate, inspect, flagbind, exec/*, log/*, crypto, sysinfo, rc | Constants, I/O, formatting, external commands |
 | Domain | [DETAILED_DESIGN-domain.md](DETAILED_DESIGN-domain.md) | entity, entry, context/*, drift, index, task, tidy, trace, journal/*, memory, notify, claude | Core business logic and data types |
-| MCP | [DETAILED_DESIGN-mcp.md](DETAILED_DESIGN-mcp.md) | mcp/proto, mcp/handler, mcp/server/*, mcp/session | JSON-RPC 2.0 server, tools, resources, prompts |
+| MCP | [DETAILED_DESIGN-mcp.md](DETAILED_DESIGN-mcp.md) | mcp/proto, mcp/handler, mcp/server/*, entity.MCPSession | JSON-RPC 2.0 server, tools, resources, prompts |
 | CLI | [DETAILED_DESIGN-cli.md](DETAILED_DESIGN-cli.md) | bootstrap, cli/parent, 34 command packages | Command registration, groups, taxonomy |
 | Output | [DETAILED_DESIGN-output.md](DETAILED_DESIGN-output.md) | write/*, err/*, assets/read/* | Terminal formatting, error constructors, text lookup |
 

.context/LEARNINGS.md

@@ -17,6 +17,7 @@ DO NOT UPDATE FOR:
 <!-- INDEX:START -->
 | Date | Learning |
 |----|--------|
+| 2026-04-09 | Pad index shifting is a real UX bug in batch operations |
 | 2026-04-08 | fmt.Fprintf to strings.Builder silently discards errors |
 | 2026-04-08 | AST audit tests must cover unexported functions too |
 | 2026-04-06 | Agents ignore system-reminder content without explicit relay instructions |
@@ -111,6 +112,16 @@ DO NOT UPDATE FOR:
 
 ---
 
+## [2026-04-09-001323] Pad index shifting is a real UX bug in batch operations
+
+**Context**: ctx pad rm 10; rm 11; rm 12 deleted wrong entries because indices shifted after each deletion
+
+**Lesson**: Any ID-based system where users chain operations needs stable IDs. Look-then-act is safe for single ops; look-then-batch-act breaks with shifting indices
+
+**Application**: Both pad and remind now use stable IDs with batch delete and range support. Apply same pattern to any future numbered-list subsystem
+
+---
+
 ## [2026-04-08-074612] fmt.Fprintf to strings.Builder silently discards errors
 
 **Context**: golangci-lint errcheck allows fmt.Fprintf to strings.Builder because Write never fails, but project convention says zero silent discard

.context/TASKS.md

@@ -42,7 +42,7 @@ TASK STATUS LABELS:
 
 ### Phase -2: Task completion nudge:
 
-- [ ] Move 6 grandfathered cross-package MCP types to entity/ #session:cc97cb0d #branch:main #commit:e8d5c60a #added:2026-04-08-074620
+- [x] Move 6 grandfathered cross-package MCP types to entity/ #session:cc97cb0d #branch:main #commit:e8d5c60a #added:2026-04-08-074620
 
 - [ ] Design UserPromptSubmit hook that runs `make audit` at
   session start and surfaces failures as a consolidation-debt

internal/assets/read/lookup/state.go

@@ -9,13 +9,6 @@ package lookup
 // stopWordsMap holds words excluded from search indexing.
 var stopWordsMap map[string]bool
 
-// commandEntry is a single YAML-backed description with
-// short and optional long forms.
-type commandEntry struct {
-	Short string `yaml:"short"`
-	Long  string `yaml:"long"`
-}
-
 var (
 	// CommandsMap maps command description keys to their YAML entries.
 	CommandsMap map[string]commandEntry

internal/assets/read/lookup/types.go

@@ -15,3 +15,10 @@ type ConfigPattern struct {
 	Pattern string
 	Topic   string
 }
+
+// commandEntry is a single YAML-backed description with
+// short and optional long forms.
+type commandEntry struct {
+	Short string `yaml:"short"`
+	Long  string `yaml:"long"`
+}

internal/audit/cross_package_types_test.go

@@ -15,11 +15,11 @@ import (
 )
 
 // grandfatheredCrossPackageTypes is the count of pre-existing
-// cross-package type violations in mcp/ sibling subpackages.
-// These were exposed by hardening the sameModule heuristic
-// to stop blanket-exempting intra-module sibling sharing.
-// Reduce as violations are moved to entity/.
-const grandfatheredCrossPackageTypes = 6
+// cross-package type violations. Kept at zero: every new
+// violation must be addressed by moving the type to entity/
+// or restructuring the package boundary to eliminate the
+// crossing.
+const grandfatheredCrossPackageTypes = 0
 
 // DO NOT add entries here to make tests pass. New code must
 // conform to the check. Widening requires a dedicated PR with
@@ -247,7 +247,7 @@ func sameModule(a, b string) bool {
 		}
 	}
 	// Parent consuming its own child subpackage
-	// (e.g. mcp/server using mcp/server/poll.Poller).
+	// (e.g. mcp/server using mcp/server/dispatch/poll.Poller).
 	if isChildPackage(a, b) || isChildPackage(b, a) {
 		return true
 	}