Skip to content

Commit acc80eb

Browse files
claudeclaude
committed
chore(workitems): land TallFern WI + DEC-FierceFern + admin logs on main
These accumulated in this session's main-thread MCP calls (creating the WorkItem, recording the architectural DEC, transition events) but did not ride on DeepFinch's PR #38 branch. Bringing them onto main so the v0.26.0 tag captures the complete record. - BACK-TallFern (mcp-gateway-adoption epic, transitioned to done after PR #38 merged) - DEC-FierceFern (4 UX defaults — Read hook BLOCK strict, TM auto- scaffold always, audit JSON output, dispatch hook over slash cmd) - 7 auto-emitted LogEntries Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 817a9d1 commit acc80eb

8 files changed

Lines changed: 240 additions & 0 deletions

‎context/decisions/DEC-20260510_0758-FierceFern-mcp-gateway-adoption-ux-defaults-for.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
---
2+
apiVersion: processkit.projectious.work/v2
3+
kind: DecisionRecord
4+
metadata:
5+
id: DEC-20260510_0758-FierceFern-mcp-gateway-adoption-ux-defaults-for
6+
created: '2026-05-10T07:58:21+00:00'
7+
spec:
8+
title: MCP gateway adoption — UX defaults for v0.26.0 integration
9+
state: accepted
10+
decision: |
11+
Ship four UX defaults in v0.26.0 to close the gap between the v2 compliance contract and observed agent behavior:
12+
13+
1. **PreToolUse Read hook**: BLOCK Read for paths matching `context/{workitems,decisions,artifacts,team-members,scopes,gates,actors,roles,bindings}/*.md` (canonical entity dirs). WARN-only for grayer paths (`logs/`, `schemas/`, `migrations/applied/`, `team-members/<slug>/{persona.md,card.json,knowledge/,journal/,...}` non-entity sub-files).
14+
15+
2. **`create_team_member` always auto-scaffolds**: 6 tier subdirs (`knowledge/`, `journal/`, `skills/`, `relations/`, `lessons/`, `private/`) each with `.gitkeep`, plus `card.json` and `persona.md` templates rendered from the TeamMember spec. No opt-out parameter.
16+
17+
3. **`run_pk_doctor` and `run_pk_release_audit` MCP wrappers return structured JSON**: `{findings: [...], totals: {error, warn, info}, exit_code}`. doctor.py and release_audit.py grow a `--json` flag if not already present; the MCP wrapper invokes the script and parses.
18+
19+
4. **Subagent dispatch enforcement is strengthened by hook, not by a new slash command**: PreToolUse hook on the `Agent` tool validates that a `route_task` call happened earlier in the same turn (per-turn-state in `context/.state/skill-gate/`). Bare-model dispatch fails the hook. No `/pk-dispatch` command in v0.26.0.
20+
context: 'Session 2026-05-10 surfaced systematic regression: even with the v2 contract
21+
directing agents to use index-management for entity reads and route_task before
22+
write-side ops, agents (including this session''s main agent) defaulted to Read/find/grep/Edit
23+
on context/ paths. Root causes: tool-default bias, real gateway coverage gaps,
24+
hook becomes background noise, knowing the file path defeats the gateway. WorkItem
25+
BACK-TallFern enumerates the gaps; these four decisions set the UX defaults for
26+
the implementation.'
27+
rationale: |
28+
- Choice 1 (BLOCK strict, WARN lenient): WARN alone reproduces the failure mode we observed (background noise). Full BLOCK risks edge cases. Strict-on-canonical + WARN-on-gray is the compromise that preserves high-value enforcement without breaking grayer reads (logs and applied migrations are append-only and frequently scanned for context).
29+
- Choice 2 (always auto-scaffold): Closes the team_consistency.tier_missing class of bug at source. Cost is a few empty dirs; benefit is no derived project ever lands a half-formed TeamMember entity again.
30+
- Choice 3 (structured JSON): Enables agents to iterate, filter, and route audit findings to other MCP calls. Raw text would force re-parsing.
31+
- Choice 4 (hook over slash command): Same enforcement bar via lower surface area; no new entry point for users to learn. /pk-dispatch can ship in v0.27 if the hook proves insufficient.
32+
alternatives:
33+
- option: WARN-only Read hook
34+
reason_rejected: reproduces background-noise failure mode
35+
- option: Full BLOCK on all context/ Read
36+
reason_rejected: edge cases (logs, migrations/applied) need ad-hoc scan access
37+
- option: create_team_member opt-in scaffold
38+
reason_rejected: callers forget; bug recurs
39+
- option: /pk-dispatch slash command
40+
reason_rejected: extra surface for same enforcement; defer until proven necessary
41+
consequences: |
42+
- v0.26.0 release blocks until SUB-1..SUB-5 land
43+
- Derived projects on v0.26.0 will see Read fail on canonical entity paths — needs a clear migration note in the v0.26.0 release notes ("if your scripts cat or grep entity files, replace with get_entity / list_entities / search_entities")
44+
- pk-doctor and release-audit gain --json flags; existing text output preserved as default for human invocation
45+
deciders:
46+
- TEAMMEMBER-thrifty-otter
47+
related_workitems:
48+
- BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
49+
decided_at: '2026-05-10T07:58:21+00:00'
50+
---

‎context/logs/2026/05/LOG-20260510_0751-GentleDawn-workitem-created.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
apiVersion: processkit.projectious.work/v2
3+
kind: LogEntry
4+
metadata:
5+
id: LOG-20260510_0751-GentleDawn-workitem-created
6+
created: '2026-05-10T07:51:52+00:00'
7+
spec:
8+
event_type: workitem.created
9+
timestamp: '2026-05-10T07:51:52+00:00'
10+
summary: 'Created WorkItem ''BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps'':
11+
''MCP gateway adoption: close usage gaps so Claude Code agents default to gateway
12+
over direct file ops'''
13+
subject: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
14+
subject_kind: WorkItem
15+
actor: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
16+
---

‎context/logs/2026/05/LOG-20260510_0758-GentleEmber-workitem-transitioned.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
apiVersion: processkit.projectious.work/v2
3+
kind: LogEntry
4+
metadata:
5+
id: LOG-20260510_0758-GentleEmber-workitem-transitioned
6+
created: '2026-05-10T07:58:28+00:00'
7+
spec:
8+
event_type: workitem.transitioned
9+
timestamp: '2026-05-10T07:58:28+00:00'
10+
summary: Transitioned WorkItem 'BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps'
11+
from 'backlog' to 'in-progress'
12+
subject: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
13+
subject_kind: WorkItem
14+
actor: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
15+
---

‎context/logs/2026/05/LOG-20260510_0758-RapidGrove-decision-created.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
apiVersion: processkit.projectious.work/v2
3+
kind: LogEntry
4+
metadata:
5+
id: LOG-20260510_0758-RapidGrove-decision-created
6+
created: '2026-05-10T07:58:21+00:00'
7+
spec:
8+
event_type: decision.created
9+
timestamp: '2026-05-10T07:58:21+00:00'
10+
summary: 'Created DecisionRecord ''DEC-20260510_0758-FierceFern-mcp-gateway-adoption-ux-defaults-for'':
11+
''MCP gateway adoption — UX defaults for v0.26.0 integration'''
12+
subject: DEC-20260510_0758-FierceFern-mcp-gateway-adoption-ux-defaults-for
13+
subject_kind: DecisionRecord
14+
actor: DEC-20260510_0758-FierceFern-mcp-gateway-adoption-ux-defaults-for
15+
---

‎context/logs/2026/05/LOG-20260510_0818-KindWren-workitem-transitioned.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
apiVersion: processkit.projectious.work/v2
3+
kind: LogEntry
4+
metadata:
5+
id: LOG-20260510_0818-KindWren-workitem-transitioned
6+
created: '2026-05-10T08:18:35+00:00'
7+
spec:
8+
event_type: workitem.transitioned
9+
timestamp: '2026-05-10T08:18:35+00:00'
10+
summary: Transitioned WorkItem 'BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps'
11+
from 'in-progress' to 'review'
12+
subject: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
13+
subject_kind: WorkItem
14+
actor: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
15+
---

‎context/logs/2026/05/LOG-20260510_0843-GentleOak-workitem-transitioned.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
apiVersion: processkit.projectious.work/v2
3+
kind: LogEntry
4+
metadata:
5+
id: LOG-20260510_0843-GentleOak-workitem-transitioned
6+
created: '2026-05-10T08:43:38+00:00'
7+
spec:
8+
event_type: workitem.transitioned
9+
timestamp: '2026-05-10T08:43:38+00:00'
10+
summary: Transitioned WorkItem 'BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps'
11+
from 'review' to 'done'
12+
subject: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
13+
subject_kind: WorkItem
14+
actor: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
15+
---

‎context/logs/2026/05/LOG-20260510_0843-WildPanda-workitem-archive-moved.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
apiVersion: processkit.projectious.work/v2
3+
kind: LogEntry
4+
metadata:
5+
id: LOG-20260510_0843-WildPanda-workitem-archive-moved
6+
created: '2026-05-10T08:43:38+00:00'
7+
spec:
8+
event_type: workitem.archive-moved
9+
timestamp: '2026-05-10T08:43:38+00:00'
10+
summary: Archived terminal WorkItem 'BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps'
11+
to /workspace/context/workitems/done/2026/05/BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps.md
12+
subject: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
13+
subject_kind: WorkItem
14+
actor: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
15+
details:
16+
path: /workspace/context/workitems/done/2026/05/BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps.md
17+
---

‎context/workitems/done/2026/05/BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
apiVersion: processkit.projectious.work/v2
3+
kind: WorkItem
4+
metadata:
5+
id: BACK-20260510_0751-TallFern-mcp-gateway-adoption-close-usage-gaps
6+
created: '2026-05-10T07:51:51+00:00'
7+
labels:
8+
release: v0.26.0
9+
cluster: agent-dispatch
10+
harness: claude-code
11+
updated: '2026-05-10T08:43:38+00:00'
12+
spec:
13+
title: 'MCP gateway adoption: close usage gaps so Claude Code agents default to
14+
gateway over direct file ops'
15+
state: done
16+
type: epic
17+
priority: high
18+
description: |
19+
## Problem
20+
21+
Even with the v2 compliance contract (PR #24, NobleLeaf) explicitly directing agents to use index-management for entity reads and route_task before write-side ops, this session's tool log shows systematic regression to direct file ops:
22+
23+
- `Read /workspace/context/team-members/finn/team-member.md` instead of `get_team_member(slug='finn')`
24+
- `Read /workspace/context/migrations/applied/MIG-LOCK-*.md` instead of `get_migration(id=...)`
25+
- `find context/team-members -maxdepth 1 -type d` instead of `list_team_members`
26+
- `ls context/team-members/finn/` (direct contract violation)
27+
- Edit on `context/schemas/migration.yaml` (no MCP equivalent exists)
28+
- `uv run context/skills/processkit/pk-doctor/scripts/doctor.py` instead of an MCP wrapper
29+
30+
Root causes:
31+
1. Tool-default bias: Bash/Read/Edit are top-level; MCP needs ToolSearch first
32+
2. Real gaps in gateway coverage (schema editing, script wrappers, scaffolding)
33+
3. Compliance hook becomes background noise after acknowledge_contract
34+
4. Knowing the file path defeats the gateway (Read is one call vs route_task → get_entity)
35+
5. Subagents inherit the parent agent's pattern
36+
37+
## Cost
38+
- Bypasses index re-validate that get_entity runs
39+
- Skips routing telemetry (route_task dataset thins)
40+
- Drift between contract and behavior (the very failure mode of gh#17/#18/#19)
41+
42+
## Scope (Tier 1 — close real gaps with new tools)
43+
44+
1. **`get_entity_by_path(path)`** in index-management — single tool that takes a relative path and dispatches to the right `get_*`. Removes the ID-vs-path mental overhead.
45+
2. **`list_entities(kind, state=None, limit=50)`** in index-management — unified listing across kinds; replaces per-kind `list_*` shortcuts.
46+
3. **`run_pk_doctor(check=None, fix=None)`** in pk-doctor — MCP wrapper around doctor.py returning structured JSON findings; agent-friendly iteration.
47+
4. **`run_pk_release_audit(tree=None)`** in release-audit — same wrapper pattern.
48+
5. **`create_team_member` auto-scaffolds**: 6 tier subdirs (knowledge/journal/skills/relations/lessons/private with .gitkeep) + card.json template + persona.md template. Closes the team_consistency.tier_missing class of bug at source (the bug we just patched).
49+
50+
## Scope (Tier 2 — Claude Code harness improvements)
51+
52+
6. **PreToolUse hook on Read for `context/<entity-dir>/*.md`** — intercept and emit nudge ("use get_entity instead, route_task → get_entity is one extra call"). Decision needed: BLOCK or WARN.
53+
7. **PreToolUse hook on Bash for `find|grep|ls|cat` patterns over `context/`** — same nudge pattern.
54+
8. **SessionStart preload of common gateway tools** — eliminate ToolSearch friction for the top-N tools (acknowledge_contract, route_task, find_skill, get_*, list_*, create_*).
55+
9. **Subagent template** that auto-includes contract reminders + route_task handshake.
56+
57+
## Scope (Tier 3 — workflow / docs)
58+
59+
10. compliance-contract.md: add "Preferred MCP entry points by task type" reference table.
60+
11. compliance-contract.md: explicit "Read is OK for non-entity files" clarification (skill code, configs, docs).
61+
12. docs/harness-claude-code.md: section on common MCP calls + Claude Code shortcuts; document the pre-loading recipe.
62+
63+
## Deliverable surface (src/)
64+
65+
All Tier 1 tools ship in their respective skill MCP servers (mirrored to src/context/...).
66+
Tier 2 hooks ship as additions to .claude/settings.json template + hook scripts under skill-gate.
67+
Tier 3 docs ship in compliance-contract.md and docs/harness-claude-code.md.
68+
69+
## Target release
70+
v0.26.0 (not yet tagged). This work integrates into the release before tagging.
71+
72+
## Sub-WorkItems (to be split during implementation)
73+
- SUB-1: index-management — get_entity_by_path + list_entities
74+
- SUB-2: pk-doctor + release-audit MCP wrappers
75+
- SUB-3: team-manager — create_team_member auto-scaffold
76+
- SUB-4: skill-gate — PreToolUse Read/Bash hooks (gated on architectural answers)
77+
- SUB-5: docs + contract updates
78+
79+
## Architectural questions outstanding
80+
See AskUserQuestion.
81+
started_at: '2026-05-10T07:58:28+00:00'
82+
completed_at: '2026-05-10T08:43:38+00:00'
83+
---
84+
85+
## Transition note (2026-05-10T07:58:28+00:00)
86+
87+
Architectural decisions accepted by owner via AskUserQuestion. DEC-20260510_0758-FierceFern recorded. Dispatching Sonnet senior software-engineer to implement Tier 1 + Tier 2 + Tier 3 in a single coordinated branch for v0.26.0 integration.
88+
89+
90+
## Transition note (2026-05-10T08:18:35+00:00)
91+
92+
Branch feat/v0.26.0-mcp-gateway-adoption pushed. 5 commits: T1.1 get_entity_by_path, T1.2 list_entities, T1.3 run_pk_doctor MCP wrapper + --json flag, T1.4 run_pk_release_audit MCP wrapper + --json flag, T1.5 create_team_member auto-scaffold, T2.1 check_entity_read.py PreToolUse BLOCK hook, T2.2 check_route_task_before_agent.py PreToolUse BLOCK hook + route_task marker writing, T3.1 compliance-contract MCP entry points table + Read clarification, T3.2 harness-claude-code.md adoption guide. Tests: 9 index-management + 20+22 doctor/audit + 44 hook assertions + 97 team-manager all green. Doctor: 0E/0W/21I. Release-audit: 0E/0W. Do not open PR — Cora reviews.
93+
94+
95+
## Transition note (2026-05-10T08:43:38+00:00)
96+
97+
DeepFinch (Sonnet) shipped Tier 1 + Tier 2 + Tier 3 in 5 commits. PR #38 merged to main (commit 817a9d1). Audits remain GREEN: pk-doctor 0E/0W/21I, release-audit 0E/0W/1461I.

0 commit comments

Comments
 (0)