feat(mcp): define explicit active-blocker semantics for observation consumers

Open
  • Is something wrong?
#2,186 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
go
Domain
api, tooling

Research direction

Start by locating the MCP observation tools, response types, and existing contract tests; the issue does not name specific files or entry points. Read how observations are represented and returned, then identify where a documented active or resolved blocker signal could fit. Done means the contract is documented and tests show that explicit active blockers are reported while historical text mentioning “blocked” is not.

Written by the indexing model from the issue text.

Description

status:needs-review type:feature
Existing Issue Search
  • I searched existing issues and will add evidence to a canonical tracker when applicable.
🔍 Observed Consequence

Observation consumers do not have a documented, machine-readable contract for distinguishing an active blocker from historical prose that merely mentions blocking.

In a Pi/Gentle Shell status integration, a completed architecture observation and a discovery observation containing the word blocked were both reported as active blockers. The sidebar showed Blockers · 2 and the host status showed 2 blocked, even though the tracked ODD feature was completed and no active blocker existed.

This makes blocker counts dependent on each client's text-matching heuristics. Historical summaries, completed feature records, and diagnostic notes can therefore become false active blockers.

💡 Desired Outcome

Engram provides one authoritative structured signal for active blockers, so consumers can render blocker counts without scanning arbitrary titles or content.

Historical observations should remain searchable, but words such as blocked, waiting for, or depends on inside completed or documentary records should not make those records active blockers.

📦 Affected Area

MCP Server (tools, transport)

Release Context

Engram 3.6.0 and current main

🔄 Workarounds and Constraints

A consumer can restrict its count to observations whose type is exactly blocker, but the current public contract does not define whether that type alone means active, how a blocker is resolved, or whether another structured field should be authoritative. Free-text inference is unsafe because observation content intentionally preserves historical context.

📎 Additional Context

Proposed contract for maintainer approval:

  1. Define blockers as explicit structured state, never as a match against arbitrary title or content text.
  2. Expose active versus resolved blocker state through the MCP observation response, a documented canonical type/lifecycle rule, or a dedicated filtered query.
  3. Preserve existing observations and search behavior; this proposal should not delete or rewrite historical memory.
  4. Add contract tests proving that completed architecture, discovery, bugfix, decision, and session_summary observations may mention blocked without becoming active blockers, while an explicit active blocker remains visible.
  5. Document the rule for Pi, OpenCode, and other observation consumers so independent integrations produce consistent counts.

The immediate downstream integration can stop using text heuristics, but an upstream contract would prevent each client from inventing incompatible blocker semantics.

Dominant language
Go
Stars
7.1k
Forks
729
Avg merge
10h 51m
Merged PRs (30d)
277

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from Gentleman-Programming/engram

All issues in Gentleman-Programming/engram

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.