@jetrabbits/agentic 0.3.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.
 

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.

package/MEMORY.md

@@ -1,113 +1,67 @@
 # 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.
-
----
+Use MCP context only when it improves accuracy. Keep searches narrow.
 
 ## 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.
-
----
+- 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
 
-### Loading context — session start
-
-Query MemPalace **before** reading any source files. Orientation queries to run at the start of every session:
+MemPalace stores project memory by wing. The current project wing is the sanitized project directory basename. Cross-project Markdown knowledge belongs in `shared_docs`.
 
-```
-mempalace_search({ "query": "project architecture decisions" })
-mempalace_search({ "query": "domain entities and relationships" })
-mempalace_search({ "query": "known constraints and non-negotiables" })
-```
+### Cheap search pattern
 
-Before touching any subsystem, query for accumulated knowledge about it:
+Do not run broad startup searches. Search only for the task at hand:
 
-```
-mempalace_search({ "query": "<module or service name> design decisions" })
-mempalace_search({ "query": "<module or service name> known issues" })
+```json
+mempalace_search({
+  "query": "short exact keywords",
+  "wing": "<current_project_wing>",
+  "limit": 3,
+  "max_distance": 0.55
+})
 ```
 
-### Writing facts — when to store
+Rules:
 
-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.
+- 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.
 
-| 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
 
-### Writing facts — examples
+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.
 
-```
-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"]
-})
-```
+Store only durable, self-contained facts:
 
-```
-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"]
-})
-```
+- 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/**`.
 
-```
-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"]
-})
-```
+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({
-  "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"]
+  "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"]
 })
 ```
 
-### 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
+## Fallback
 
-When MCP providers are unavailable, fall back in this order:
+If MCP providers are unavailable, use:
 
-1. Local `docs/**` in the project repository
-2. Official upstream documentation
-3. Model knowledge (least preferred — state explicitly when used)
+1. local `docs/**`;
+2. official upstream documentation;
+3. model knowledge, explicitly marked as fallback.

package/Makefile

@@ -1,11 +1,30 @@
-.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
+.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" \
@@ -13,8 +32,12 @@ help:
 		"  test-markers  Run generated marker and idempotency tests" \
 		"  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" \
@@ -30,48 +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
-	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
+	$(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:
-	bash tests/e2e/opencode_plugins.e2e.sh
+	$(call timed_step,test-opencode-plugins,bash tests/e2e/opencode_plugins.e2e.sh)
 
 test-telegram-plugin:
-	bash tests/e2e/telegram_plugin.e2e.sh
+	$(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:
-	bash tests/e2e/real_agent_blackbox.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)
+
+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:
-	AGENTIC_REAL_BLACKBOX_ONLY=opencode-mapper 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)
 
 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"'
+	@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