@jetrabbits/agentic 0.2.0 → 0.3.1

package/AGENTS.md

@@ -16,12 +16,19 @@ project_dir/
     └── prompts/
 ```
 
+## Guidance chain
+
+1. Project `.agent/` baseline
+2. `.agent/rules/*` — load all
+3. `.agent/skills/*/SKILL.md` — load only the skill matching the current task
+4. `.agent/workflows/*` — load the workflow matching the triggered command
+
 **Discovery patterns:**
 
-- `project_dir/.agent/rules/*`
-- `project_dir/.agent/skills/*`
-- `project_dir/.agent/workflows/*`
-- `project_dir/.agent/prompts/*`
+- `.agent/rules/*.md`
+- `.agent/skills/*/SKILL.md`
+- `.agent/workflows/*.md`
+- `.agent/prompts/*.md`
 
 Prefer relative paths in references inside markdown files.
 
@@ -70,18 +77,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
-
-- 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
+### MCP Memory Providers
 
-- 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,29 @@
 # Changelog
 
+## v0.3.1
+
+- Added project-level OpenCode plugin settings in `.agentic.json`, including Telegram `botToken` and `chatId` when `telegram-notification` is enabled.
+- Renamed the OpenCode optional plugin menu entry to `telegram-notification` while preserving the old `telegram-opencode-notifier` alias for compatibility.
+- Changed `telegram-notification` runtime credentials to read from the target project's `.agentic.json` instead of Telegram environment variables.
+- Removed Telegram message formatting entirely: notifications are sent as plain text without `parse_mode`, MarkdownV2 escaping, or markdown-to-Telegram conversion.
+- Added interactive Context7 key mode selection with English menu entries for keyless setup or entering `CONTEXT7_API_KEY`.
+- Removed the post-install Context7 "add API key later" path/example guidance because key selection now happens during setup.
+- Extended `agent-model-mapper` model discovery to include active providers from `~/.local/share/opencode/auth.json` and non-deprecated models from `~/.cache/opencode/models.json`.
+- Added a Confirm/Cancel save step after OpenCode role model selection before writing `.opencode/opencode.json`.
+- Preserved OpenCode plugin settings across manifest replay/re-install so automated sync does not prompt again or lose project-level credentials.
+- Updated OpenCode, Context7, Telegram, and lifecycle docs plus deterministic e2e coverage for the new configuration flow.
+
+## 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,67 @@
+# MEMORY — MCP context providers
+
+Use MCP context only when it improves accuracy. Keep searches narrow.
+
+## Context7
+
+- Use Context7 for external framework, library, SDK, API, and setup docs.
+- Resolve the exact package/framework first; ask for focused docs only.
+- If Context7 is unavailable, use local `docs/**`, then official upstream docs.
+
+## MemPalace
+
+MemPalace stores project memory by wing. The current project wing is the sanitized project directory basename. Cross-project Markdown knowledge belongs in `shared_docs`.
+
+### Cheap search pattern
+
+Do not run broad startup searches. Search only for the task at hand:
+
+```json
+mempalace_search({
+  "query": "short exact keywords",
+  "wing": "<current_project_wing>",
+  "limit": 3,
+  "max_distance": 0.55
+})
+```
+
+Rules:
+
+- Keep `query` short; put background in `context` only if needed.
+- Use `wing` whenever you know it.
+- Use `limit: 3` by default; raise it only when evidence is thin.
+- Use `max_distance` around `0.4-0.6` for precise fact lookup.
+- Search `shared_docs` only for reusable docs or cross-project behavior.
+- Call `mempalace_list_wings` or `mempalace_list_rooms` only when the wing or room is unknown.
+- Add `room` only after confirming the room name.
+
+### Writing facts
+
+Use `mempalace_store` proactively when a durable fact is discovered, decided, or corrected. Do not wait for a later search to make project knowledge persistent.
+
+Store only durable, self-contained facts:
+
+- architecture decisions and rationale;
+- domain rules and API/data contracts;
+- non-obvious integrations or constraints;
+- known issues, bottlenecks, and mitigations;
+- team conventions not already captured in `docs/**`.
+
+Store one fact per call, tagged with project/module/domain nouns. Write project facts to the current project wing. Write to `shared_docs` only when the knowledge is intentionally reusable across projects.
+
+```json
+mempalace_store({
+  "wing": "<current_project_wing>",
+  "room": "<known_room_if_confirmed>",
+  "text": "Durable fact stated as a complete sentence with enough context to stand alone.",
+  "tags": ["project", "module", "domain"]
+})
+```
+
+## Fallback
+
+If MCP providers are unavailable, use:
+
+1. local `docs/**`;
+2. official upstream documentation;
+3. model knowledge, explicitly marked as fallback.

package/Makefile

@@ -1,17 +1,45 @@
-.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-all test-cli test-tui test-cross test-doctor test-markers test-opencode-plugins test-telegram-plugin test-ubuntu-blackbox test-real-agent-doctor test-real-blackbox test-real-blackbox-codex test-real-blackbox-opencode test-real-blackbox-telegram test-real-opencode-mapper test-coverage _test-coverage-steps lint fmt clean build assess-areas
+
+define timed_step
+	@label='$(1)'; \
+	start=$$(date +%s); \
+	timestamp=$$(date '+%Y-%m-%d %H:%M:%S'); \
+	printf '%s [make-timing] START %s\n' "$$timestamp" "$$label"; \
+	$(2); \
+	status=$$?; \
+	end=$$(date +%s); \
+	elapsed=$$((end - start)); \
+	timestamp=$$(date '+%Y-%m-%d %H:%M:%S'); \
+	if [ "$$status" -eq 0 ]; then \
+	  printf '%s [make-timing] OK %s elapsed=%ss\n' "$$timestamp" "$$label" "$$elapsed"; \
+	else \
+	  printf '%s [make-timing] FAIL %s elapsed=%ss exit=%s\n' "$$timestamp" "$$label" "$$elapsed" "$$status"; \
+	fi; \
+	exit "$$status"
+endef
 
 help:
 	@printf '%s\n' \
 		"Available targets:" \
 		"  install       Install local development prerequisites" \
 		"  dev           Show local development entrypoints" \
-		"  test          Run end-to-end tests (all groups)" \
+		"  test          Run fast deterministic end-to-end tests" \
+		"  test-all      Run fast tests, real blackbox, and coverage" \
 		"  test-cli      Run CLI end-to-end tests" \
 		"  test-tui      Run TUI end-to-end tests" \
 		"  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-ubuntu-blackbox   Run make test in a clean Docker Ubuntu image" \
+		"  test-real-agent-doctor  Run real agent doctor checks" \
+		"  test-real-blackbox      Run real Codex/OpenCode/Telegram blackbox tests" \
+		"  test-real-blackbox-codex  Run real Codex blackbox test" \
+		"  test-real-blackbox-opencode  Run real OpenCode blackbox test" \
+		"  test-real-blackbox-telegram  Run real OpenCode Telegram blackbox test" \
+		"  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" \
@@ -25,29 +53,83 @@ dev:
 	@printf '%s\n' "Use ./agentic tui or ./agentic install ..."
 
 test:
-	bash tests/e2e/cli.e2e.sh
-	bash tests/e2e/tui.e2e.sh
-	bash tests/e2e/cross.e2e.sh
-	bash tests/e2e/doctor.e2e.sh
-	bash tests/e2e/markers.e2e.sh
+	$(call timed_step,test-cli,bash tests/e2e/cli.e2e.sh)
+	$(call timed_step,test-tui,bash tests/e2e/tui.e2e.sh)
+	$(call timed_step,test-cross,bash tests/e2e/cross.e2e.sh)
+	$(call timed_step,test-opencode-plugins,bash tests/e2e/opencode_plugins.e2e.sh)
+	$(call timed_step,test-telegram-plugin,bash tests/e2e/telegram_plugin.e2e.sh)
+
+test-all:
+	$(call timed_step,test,$(MAKE) test)
+	$(call timed_step,test-doctor,bash tests/e2e/doctor.e2e.sh)
+	$(call timed_step,test-markers,bash tests/e2e/markers.e2e.sh)
+	$(call timed_step,test-real-blackbox-codex,AGENTIC_REAL_BLACKBOX_ONLY=codex bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-blackbox-opencode,AGENTIC_REAL_BLACKBOX_ONLY=opencode bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-opencode-mapper,AGENTIC_REAL_BLACKBOX_ONLY=opencode-mapper bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-blackbox-telegram,AGENTIC_REAL_BLACKBOX_ONLY=telegram bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-coverage,$(MAKE) test-coverage)
 
 test-cli:
-	bash tests/e2e/cli.e2e.sh
+	$(call timed_step,test-cli,bash tests/e2e/cli.e2e.sh)
 
 test-tui:
-	bash tests/e2e/tui.e2e.sh
+	$(call timed_step,test-tui,bash tests/e2e/tui.e2e.sh)
 
 test-cross:
-	bash tests/e2e/cross.e2e.sh
+	$(call timed_step,test-cross,bash tests/e2e/cross.e2e.sh)
 
 test-doctor:
-	bash tests/e2e/doctor.e2e.sh
+	$(call timed_step,test-doctor,bash tests/e2e/doctor.e2e.sh)
 
 test-markers:
-	bash tests/e2e/markers.e2e.sh
+	$(call timed_step,test-markers,bash tests/e2e/markers.e2e.sh)
+
+test-opencode-plugins:
+	$(call timed_step,test-opencode-plugins,bash tests/e2e/opencode_plugins.e2e.sh)
+
+test-telegram-plugin:
+	$(call timed_step,test-telegram-plugin,bash tests/e2e/telegram_plugin.e2e.sh)
+
+test-ubuntu-blackbox:
+	$(call timed_step,test-ubuntu-blackbox,bash tests/e2e/ubuntu_blackbox.e2e.sh)
 
 test-real-agent-doctor:
-	bash tests/e2e/real_agent_doctor.e2e.sh
+	$(call timed_step,test-real-agent-doctor,bash tests/e2e/real_agent_doctor.e2e.sh)
+
+test-real-blackbox:
+	$(call timed_step,test-real-blackbox-codex,AGENTIC_REAL_BLACKBOX_ONLY=codex bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-blackbox-opencode,AGENTIC_REAL_BLACKBOX_ONLY=opencode bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-opencode-mapper,AGENTIC_REAL_BLACKBOX_ONLY=opencode-mapper bash tests/e2e/real_agent_blackbox.e2e.sh)
+	$(call timed_step,test-real-blackbox-telegram,AGENTIC_REAL_BLACKBOX_ONLY=telegram bash tests/e2e/real_agent_blackbox.e2e.sh)
+
+test-real-blackbox-codex:
+	$(call timed_step,test-real-blackbox-codex,AGENTIC_REAL_BLACKBOX_ONLY=codex bash tests/e2e/real_agent_blackbox.e2e.sh)
+
+test-real-blackbox-opencode:
+	$(call timed_step,test-real-blackbox-opencode,AGENTIC_REAL_BLACKBOX_ONLY=opencode bash tests/e2e/real_agent_blackbox.e2e.sh)
+
+test-real-blackbox-telegram:
+	$(call timed_step,test-real-blackbox-telegram,AGENTIC_REAL_BLACKBOX_ONLY=telegram bash tests/e2e/real_agent_blackbox.e2e.sh)
+
+test-real-opencode-mapper:
+	$(call timed_step,test-real-opencode-mapper,AGENTIC_REAL_BLACKBOX_ONLY=opencode-mapper bash tests/e2e/real_agent_blackbox.e2e.sh)
+
+test-coverage:
+	@if [ -n "$${AGENTIC_COVERAGE_TRACE_FILE:-}" ]; then \
+	  trace_file="$$AGENTIC_COVERAGE_TRACE_FILE"; \
+	else \
+	  trace_file="$$(mktemp /tmp/agentic-coverage.XXXXXX)"; \
+	fi; \
+	$(MAKE) _test-coverage-steps AGENTIC_COVERAGE_TRACE_FILE="$$trace_file"
+
+_test-coverage-steps:
+	$(call timed_step,test-coverage-agentic,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/agentic.e2e.sh >/tmp/agentic-coverage-agentic.log 2>&1)
+	$(call timed_step,test-coverage-tui,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/tui.e2e.sh >/tmp/agentic-coverage-tui.log 2>&1)
+	$(call timed_step,test-coverage-cross,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/cross.e2e.sh >/tmp/agentic-coverage-cross.log 2>&1)
+	$(call timed_step,test-coverage-markers,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/markers.e2e.sh >/tmp/agentic-coverage-markers.log 2>&1)
+	$(call timed_step,test-coverage-cli,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/cli.e2e.sh >/tmp/agentic-coverage-cli.log 2>&1)
+	$(call timed_step,test-coverage-doctor,AGENTIC_COVERAGE_TRACE_FILE="$(AGENTIC_COVERAGE_TRACE_FILE)" AGENTIC_TEST_CLI="$(CURDIR)/tests/e2e/coverage_shim.sh" bash tests/e2e/doctor.e2e.sh >/tmp/agentic-coverage-doctor.log 2>&1)
+	$(call timed_step,test-coverage-parse,bash tests/e2e/coverage_parse.sh "$(AGENTIC_COVERAGE_TRACE_FILE)")
 
 lint:
 	bash -n agentic

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.
 
 ---