jorgex-stack 1.9.70 → 1.9.71

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.9.70",
+  "version": "1.9.71",
   "description": "Harness multi-agente portable: instala la config JorgeX (agentes, skills, hooks, Engram, MCPs) en Claude Code, Codex CLI, OpenCode y Pi",
   "type": "module",
   "license": "MIT",

package/stack/agents/comment-fixer.md

@@ -31,10 +31,10 @@ You fix comments directly instead of reporting suggestions: trivial comment work
 
 1. **Factual accuracy**: comments that no longer match what the code does → correct them.
 2. **Worthless comments**: comments that restate obvious code → remove them.
-3. **Missing critical context**: an undocumented assumption or non-obvious "why" worth one line → add it.
+3. **Missing critical context**: a verified, undocumented assumption or non-obvious "why" needed to use or change the code safely → add it.
 4. **Misleading elements**: wording that could be misread → clarify.
 
-Match the project's comment conventions: density, language, format. When in doubt, fewer comments — explain why, not what.
+Apply the shared system prompt's **Code comments** policy; follow local language and format, not density. Leave comments that already provide useful, accurate context untouched; cleanup is not a quota or a requirement to produce edits. Do not edit docstrings used as runtime metadata within this comments-only scope: report necessary contract changes to their owner.
 
 ## Output format
 

package/stack/skills/diagnose/SKILL.md

@@ -23,6 +23,8 @@ Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give
 
 ### Ways to construct one — try them in roughly this order
 
+Inspect the project's existing runner, fixtures, helpers and diagnostic commands first. Reuse the closest suitable harness; the options below are not an instruction to build a second testing stack. Apply `lean-code`'s diagnostic tooling policy before adding or retaining tooling.
+
 1. **Failing test** at whatever seam reaches the bug — unit, integration, e2e.
 2. **Curl / HTTP script** against a running dev server.
 3. **CLI invocation** with a fixture input, diffing stdout against a known-good snapshot.
@@ -38,7 +40,7 @@ Build the right feedback loop, and the bug is 90% fixed.
 
 ### Tighten the loop
 
-Treat the loop as a product. Once you have _a_ loop, **tighten it**:
+Tighten the loop for this investigation, not into a permanent product:
 
 - Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
 - Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
@@ -134,7 +136,9 @@ Required before declaring done:
 - [ ] Original repro no longer reproduces (re-run the Phase 1 loop)
 - [ ] Regression test passes (or absence of seam is documented)
 - [ ] All `[DEBUG-...]` instrumentation removed (`grep` the prefix)
-- [ ] Throwaway prototypes deleted (or moved to a clearly-marked debug location)
+- [ ] Throwaway probes, scripts, harnesses and their owned resources cleaned up; moving them to a debug folder is not cleanup. Retain tooling only when the recurring need, consumer, harness gap and maintenance owner are justified under `lean-code`; preserve the regression test.
 - [ ] The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns
 
+Keep compact, redacted, reproducible evidence in the existing task or PR: exact command, relevant environment/version and fixture or seed, observed failure and post-fix result. Distinguish verified observations from hypotheses. Preserve the first failure and any necessary diagnostic artifact when it carries unique evidence; do not retain full dumps or disposable environments by default. Report cleanup that could not safely finish.
+
 **Then ask: what would have prevented this bug?** If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to the `/improve-codebase-architecture` skill with the specifics. Make the recommendation **after** the fix is in, not before — you have more information now than when you started.

package/stack/skills/lean-code/SKILL.md

@@ -60,6 +60,10 @@ Do not add a new dependency unless the task explicitly requires it or the projec
 Before adding a new helper, wrapper, abstraction, or dependency, run the ladder again.
 Prefer the narrowest change that solves the real need.
 
+### Diagnostic tooling
+
+Reuse the project's runner, fixtures, helpers and existing diagnostic commands before building a harness. New probes, replay scripts and diagnostic harnesses are temporary by default, with explicit resource ownership and automatic teardown arranged before execution. Keep tooling only for a concrete recurring need: identify its consumer, why the existing harness cannot cover it, and who maintains it in the current task or PR. A successful one-off investigation alone does not justify a permanent command, framework or dependency. Preserve the authoritative regression test and compact reproduction evidence, not the disposable environment.
+
 ### Review / simplification
 
 Use it as a bloat filter: delete, stdlib, native/platform, reuse, or shrink.

package/stack/skills/mcp-builder/reference/python_mcp_server.md

@@ -275,7 +275,9 @@ async def get_user(user_id: str) -> Dict[str, Any]:
 
 ## Tool Docstrings
 
-Every tool must have comprehensive docstrings with explicit type information:
+Every tool needs a concise docstring describing the contract clients need: purpose, non-obvious input constraints, output shape, side effects and relevant errors. Preserve information used to generate MCP descriptions or schemas; these docstrings are runtime metadata, not merely code comments. Do not repeat types or field descriptions already exposed by the generated schema unless needed to disambiguate behavior. Document dict/JSON return structure when it is not exposed by an output schema.
+
+The example below illustrates possible contract details, not mandatory sections for every tool:
 
 ```python
 async def search_users(params: UserSearchInput) -> str:
@@ -419,7 +421,7 @@ def _handle_api_error(e: Exception) -> str:
 async def example_search_users(params: UserSearchInput) -> str:
     '''Search for users in the Example system by name, email, or team.
 
-    [Full docstring as shown above]
+    [Concise tool contract docstring]
     '''
     try:
         # Make API request using validated parameters
@@ -692,8 +694,8 @@ Before finalizing your Python MCP server implementation, ensure:
 - [ ] Annotations correctly set (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
 - [ ] All tools use Pydantic BaseModel for input validation with Field() definitions
 - [ ] All Pydantic Fields have explicit types and descriptions with constraints
-- [ ] All tools have comprehensive docstrings with explicit input/output types
-- [ ] Docstrings include complete schema structure for dict/JSON returns
+- [ ] All tools expose concise, sufficient contract descriptions without duplicating generated schema information
+- [ ] Dict/JSON return structure is exposed through an output schema or documented when no schema is exposed
 - [ ] Pydantic models handle input validation (no manual validation needed)
 
 ### Advanced Features (where applicable)
@@ -716,4 +718,4 @@ Before finalizing your Python MCP server implementation, ensure:
 - [ ] Server runs successfully: `python your_server.py --help`
 - [ ] All imports resolve correctly
 - [ ] Sample tool calls work as expected
-- [ ] Error scenarios handled gracefully
+- [ ] Error scenarios handled gracefully

package/stack/skills/xreview/SKILL.md

@@ -54,13 +54,13 @@ For a manual xreview without an explicit work context, continue without PRD/plan
 
 ## 4. Comment pass FIRST (conditional)
 
-If the diff adds or changes comments/docstrings, run `comment-fixer` ALONE before the analysts — it edits comments in place (comments only, never code), so the analysts then review a diff already clean of comment noise instead of re-reporting it or mistaking its edits for contamination.
+Inspect relevant comment/docstring hunks first. Run `comment-fixer` ALONE before the analysts when source-code comments/docstrings need an accuracy, usefulness or critical-context pass under the shared system prompt's **Code comments** policy. It already owns comment cleanup; do not add a separate cleanup agent. Instruction prose, documentation pages and illustrative code fences alone do not trigger this pass. It edits comments in place (comments only, never code), so analysts review the resulting working state rather than mistaking its edits for contamination.
 
 - Pass the frozen refs or working-state identity and the relevant comment/docstring scope.
 - When the orchestrator supplied one, pass it the same exact work context path as every other review subagent.
 - If it changed anything and the scope is a committed diff (branch/PR): comment-fixer itself never commits — YOU commit its fixes before launching reviewers, staging ONLY its files (never `-a`/`-A`). Then freeze the new candidate SHA and refresh scopes. If a commit cannot be made, report the uncommitted state; it cannot certify the committed candidate.
 - For working-tree reviews: leave its edits uncommitted (they join the user's pending work) and say so in the report.
-- If the diff touches no comments, skip it and move on.
+- If no comment pass is needed, skip it and state why. A pass that leaves all comments unchanged is valid.
 
 ## 5. Launch the remaining subagents in PARALLEL
 

package/stack/system-prompt/AGENTS.md

@@ -26,6 +26,10 @@ Ask questions when something isn't clear instead of assuming it's correct.
 - Do not add dependencies without explicit user approval.
 - Run lint and typecheck after significant changes when available.
 
+### Code comments
+
+Add comments only when they carry information the code does not make clear: a non-obvious reason, invariant, constraint or operational hazard. Do not narrate obvious code, mirror existing comment density, or add comments just because a function or test is new. Preserve contractual documentation, legal notices, directives, and critical security, concurrency or deletion context; docstrings used as runtime metadata are part of the contract, not disposable prose. Follow local language and format, without line-count or density quotas. Leaving already-clear code uncommented is valid.
+
 ---
 
 ## Default Architecture