@jetrabbits/agentic 0.2.0 → 0.3.0

package/AGENTS.md

@@ -70,18 +70,9 @@ Cross-cutting practices that apply to every project regardless of area.
 - Create or update the relevant `docs/` artifact in the same change set; do not leave behavior changes documented only in workflow outputs, tickets, or PR comments.
 - Apply the `product-owner` role to confirm that docs describe the user-facing behavior, acceptance criteria, and operational constraints of the change.
 
-### Context7 Knowledge Source
+### MCP Memory Providers
 
-- Use Context7 for framework, library, SDK, API, and setup documentation before relying on model memory.
-- Resolve the library or framework identity first, then request focused docs for the exact task and version when version matters.
-- If Context7 is unavailable, state that explicitly and fall back to local docs or official project documentation.
-
-### MemPalace + Context Strategy
-
-- If MemPalace MCP is enabled and available, load project business/domain context from MemPalace first.
-- If Context7 MCP is enabled and available, use it specifically for framework/library/API documentation.
-- If both are available, combine them: MemPalace for project/business knowledge, Context7 for framework-level references.
-- If MCP providers are unavailable, continue with standard local-repo discovery and context-building as fallback.
+See [MEMORY.md](MEMORY.md) for the full protocol: provider roles, Context7 usage, MemPalace session-start queries, fact-writing triggers, tool call examples, and fallback order.
 
 ### Code Style
 

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.3.0
+
+- Added per-agent doctor timeouts with elapsed-time and exit-status logging while keeping install non-fatal.
+- Replaced the OpenCode model checker with `agent-model-mapper` for explicit role-to-model mapping.
+- Moved `agent-model-mapper` prompts to install time so OpenCode startup stays non-blocking.
+- Removed the interactive Context7 API-key prompt and made OpenCode MemPalace project initialization optional/manual.
+- Changed Telegram notifications to read credentials from environment variables only and avoid logging secrets.
+- Added traced shell coverage tooling with a 90% `agentic` line coverage gate.
+- Added deterministic OpenCode plugin, Telegram, and doctor timeout continuation tests.
+- Added real Codex, OpenCode, and Telegram blackbox scenarios to normal `make test`.
+
 ## v0.2.0
 
 - Added `agentic --version` and version display in CLI/TUI output.

package/MEMORY.md

@@ -0,0 +1,113 @@
+# MEMORY — MCP context providers
+
+Guidance for using MemPalace and Context7 MCP servers across all agent sessions.
+
+---
+
+## Provider roles
+
+| Provider | Purpose |
+|---|---|
+| **MemPalace** | Project-specific knowledge: architecture decisions, domain rules, conventions, known issues, integration contracts |
+| **Context7** | Framework, library, SDK, and API reference documentation |
+
+Use both when available. They are complementary, not interchangeable.
+
+---
+
+## Context7
+
+- Use Context7 for framework, library, SDK, API, and setup documentation before relying on model memory.
+- Resolve the library or framework identity first, then request focused docs for the exact task and version when version matters.
+- If Context7 is unavailable, state that explicitly and fall back to local docs or official project documentation.
+
+---
+
+## MemPalace
+
+### Loading context — session start
+
+Query MemPalace **before** reading any source files. Orientation queries to run at the start of every session:
+
+```
+mempalace_search({ "query": "project architecture decisions" })
+mempalace_search({ "query": "domain entities and relationships" })
+mempalace_search({ "query": "known constraints and non-negotiables" })
+```
+
+Before touching any subsystem, query for accumulated knowledge about it:
+
+```
+mempalace_search({ "query": "<module or service name> design decisions" })
+mempalace_search({ "query": "<module or service name> known issues" })
+```
+
+### Writing facts — when to store
+
+Store a fact **immediately** when you discover or confirm any of the following. Do not wait until the end of the session — subsequent steps in the same session benefit from facts stored earlier.
+
+| Trigger | What to store |
+|---|---|
+| Architecture decision made or confirmed | Decision, alternatives considered, rationale |
+| Non-obvious module dependency or integration point | What connects to what and why |
+| Business rule or domain constraint clarified | The rule in plain language, where it is enforced |
+| Recurring bug pattern or root cause identified | Pattern description, affected area, mitigation |
+| API contract or data shape locked down | Shape, version, owning service |
+| Performance characteristic or known bottleneck noted | Where, measured or estimated, relevant thresholds |
+| Convention or team agreement not captured in docs | The agreement and its scope |
+| Environment or deployment constraint discovered | What the constraint is and which target it affects |
+
+### Writing facts — examples
+
+```
+mempalace_store({
+  "type": "architecture_decision",
+  "title": "Auth uses JWT with 15-min expiry, refresh via Redis",
+  "body": "Decided in task TASK-88. Rationale: stateless verification at API gateway; Redis holds refresh token allowlist for revocation support.",
+  "tags": ["auth", "jwt", "redis", "architecture"]
+})
+```
+
+```
+mempalace_store({
+  "type": "domain_rule",
+  "title": "Orders cannot transition from CANCELLED back to any active state",
+  "body": "Enforced in OrderStateMachine.apply(). No UI path or API endpoint bypasses this; confirmed with product owner in TASK-102.",
+  "tags": ["orders", "state-machine", "domain-rule"]
+})
+```
+
+```
+mempalace_store({
+  "type": "known_issue",
+  "title": "ReportService N+1 on invoice line items — not yet fixed",
+  "body": "Affects reports with >50 invoices. Tracked in TASK-119. Workaround: batch fetch via InvoiceRepository.findByReportId().",
+  "tags": ["reporting", "performance", "n+1"]
+})
+```
+
+```
+mempalace_store({
+  "type": "convention",
+  "title": "Feature flags go through FeatureToggleService — no direct env checks in domain code",
+  "body": "Established to keep domain layer portable. All flag reads must go through FeatureToggleService.isEnabled(flag, context).",
+  "tags": ["conventions", "feature-flags"]
+})
+```
+
+### Quality bar for stored facts
+
+- **Concrete, not vague.** "Auth uses JWT" is a fact. "Auth is secure" is not.
+- **Self-contained.** The fact must make sense without the surrounding chat context.
+- **Tagged for retrieval.** Include module names, domain nouns, and problem-type tags.
+- **One fact per store call.** Do not bundle multiple unrelated facts into one entry.
+
+---
+
+## Fallback order
+
+When MCP providers are unavailable, fall back in this order:
+
+1. Local `docs/**` in the project repository
+2. Official upstream documentation
+3. Model knowledge (least preferred — state explicitly when used)

package/Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install dev test test-cli test-tui test-cross test-doctor test-markers test-real-agent-doctor lint fmt clean build assess-areas
+.PHONY: help install dev test test-cli test-tui test-cross test-doctor test-markers test-opencode-plugins test-telegram-plugin test-real-agent-doctor test-real-blackbox test-real-opencode-mapper test-coverage lint fmt clean build assess-areas
 
 help:
 	@printf '%s\n' \
@@ -11,7 +11,12 @@ help:
 		"  test-cross    Run cross-mode end-to-end tests" \
 		"  test-doctor   Run deterministic doctor end-to-end tests" \
 		"  test-markers  Run generated marker and idempotency tests" \
-		"  test-real-agent-doctor  Run opt-in real agent doctor checks" \
+		"  test-opencode-plugins  Run OpenCode plugin deterministic tests" \
+		"  test-telegram-plugin   Run Telegram plugin deterministic tests" \
+		"  test-real-agent-doctor  Run real agent doctor checks" \
+		"  test-real-blackbox      Run real Codex/OpenCode/Telegram blackbox tests" \
+		"  test-real-opencode-mapper  Run real OpenCode mapper input blackbox" \
+		"  test-coverage  Run traced e2e coverage for agentic" \
 		"  lint          Run prompt and catalog validation" \
 		"  fmt           Check formatting hooks placeholder" \
 		"  clean         Remove generated reports" \
@@ -30,6 +35,10 @@ test:
 	bash tests/e2e/cross.e2e.sh
 	bash tests/e2e/doctor.e2e.sh
 	bash tests/e2e/markers.e2e.sh
+	bash tests/e2e/opencode_plugins.e2e.sh
+	bash tests/e2e/telegram_plugin.e2e.sh
+	bash tests/e2e/real_agent_blackbox.e2e.sh
+	$(MAKE) test-coverage
 
 test-cli:
 	bash tests/e2e/cli.e2e.sh
@@ -46,9 +55,24 @@ test-doctor:
 test-markers:
 	bash tests/e2e/markers.e2e.sh
 
+test-opencode-plugins:
+	bash tests/e2e/opencode_plugins.e2e.sh
+
+test-telegram-plugin:
+	bash tests/e2e/telegram_plugin.e2e.sh
+
 test-real-agent-doctor:
 	bash tests/e2e/real_agent_doctor.e2e.sh
 
+test-real-blackbox:
+	bash tests/e2e/real_agent_blackbox.e2e.sh
+
+test-real-opencode-mapper:
+	AGENTIC_REAL_BLACKBOX_ONLY=opencode-mapper bash tests/e2e/real_agent_blackbox.e2e.sh
+
+test-coverage:
+	AGENTIC_COVERAGE_TRACE_FILE=$$(mktemp /tmp/agentic-coverage.XXXXXX) bash -c 'AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/agentic.e2e.sh >/tmp/agentic-coverage-agentic.log 2>&1 && AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/tui.e2e.sh >/tmp/agentic-coverage-tui.log 2>&1 && AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/cross.e2e.sh >/tmp/agentic-coverage-cross.log 2>&1 && AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/markers.e2e.sh >/tmp/agentic-coverage-markers.log 2>&1 && AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/cli.e2e.sh >/tmp/agentic-coverage-cli.log 2>&1 && AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/doctor.e2e.sh >/tmp/agentic-coverage-doctor.log 2>&1 && bash tests/e2e/coverage_parse.sh "$$AGENTIC_COVERAGE_TRACE_FILE"'
+
 lint:
 	bash -n agentic
 	python3 -m py_compile scripts/build_docs_catalog.py scripts/lint_prompts.py scripts/assess_area_quality.py

package/README.md

@@ -191,8 +191,8 @@ project/.agent/
 
 - `telegram-opencode-notifier`: sends Telegram notifications when an OpenCode session becomes idle, including the final
   response or an attachment for long output.
-- `llm-quota-checker`: probes configured OpenCode models, reports available/failed models, and updates subagent model
-  settings to a working model.
+- `agent-model-mapper`: maps `.opencode/agents/*.md` roles to main and fallback OpenCode models during interactive
+  `agentic install`/`agentic tui`. OpenCode startup never prompts or writes project files.
 
 ---