jorgex-stack 1.7.5 → 1.8.0

package/README.md

@@ -210,13 +210,30 @@ Releases are triggered by push/merge to `main` and GitHub Actions; there is also
 
 Antes de instalar cualquier dependencia, `validate` ejecuta un preflight sin dependencias con Node 24 después de resolver el checkout. En un push normal solo puede omitir los pasos de validación costosos y `bump` cuando existe un tag `v<package.version>` válido y alcanzable que proporciona la base acumulada, y ese diff no contiene rutas publicables. Si falta el tag, el commit es un bump de release o anti-loop, la ejecución es `workflow_dispatch` o se proporciona `release_sha`, se mantiene el flujo completo; las refs inválidas, un tag que no sea ancestro o un error de `git diff` fallan en rojo, sin omitir silenciosamente. El preflight compara contra el tag de release de la versión actual (`v<package.version>`), no solo contra el último commit; si ese tag falta, no recurre a otro tag para justificar el skip y mantiene el flujo completo. Un diff que mezcla `.github/workflows/*` con rutas publicables mantiene el flujo completo; cuando el auto-bump es elegible, sigue permitido, y en los demás casos se conserva la guarda existente de permisos del workflow.
 
-El preflight condiciona únicamente la preparación de toolchain, la instalación de dependencias, typecheck/tests/build/upload y `bump`; las guardas existentes de registry, publicación y tag siguen siendo autoridad. Los cuatro jobs conservan permisos separados, los checkouts de solo lectura usan `persist-credentials: false`, `validate`, `bump` y `publish` tienen timeout de 10 min, `tag-release` de 5 min, y el grupo de concurrencia mantiene `cancel-in-progress: false` (no cancela una ejecución en curso; una pendiente sí puede ser reemplazada). Esto es una optimización interna de CI, no una política portable de testing ni una afirmación de ahorro de facturación medido.
+El preflight condiciona únicamente la preparación de toolchain, la instalación de dependencias, typecheck/tests/build/upload y `bump`; las guardas existentes de registry, publicación y tag siguen siendo autoridad. `validate` y `bump` declaran `contents: read`; `bump` obtiene además un token temporal del release App para el único push del bump. `publish` conserva `contents: read` + `id-token: write` para trusted publishing de npm y `tag-release` usa `GITHUB_TOKEN` con `contents: write` para el tag. Los checkouts de solo lectura usan `persist-credentials: false`, `validate`, `bump` y `publish` tienen timeout de 10 min, `tag-release` de 5 min, y el grupo de concurrencia mantiene `cancel-in-progress: false` (no cancela una ejecución en curso; una pendiente sí puede ser reemplazada). Esto es una optimización interna de CI, no una política portable de testing ni una afirmación de ahorro de facturación medido.
 
 - **Automatic patch**: if the push to `main` contains publishable changes and the current `package.json` version already exists on npm, the workflow finds the first free patch (`x+1`, `x+2`, ...), commits `chore(release): bump version to v...`, and publishes. If tag `v<package.version>` already exists, it uses that point as the accumulated base; otherwise, it falls back to `github.event.before`. Obsolete runs are aborted after `git fetch origin main --tags` if `origin/main` no longer matches `GITHUB_SHA`.
+- **Automatic patch guard**: before committing or pushing an automatic bump, the workflow validates the real working-tree/index diff. Only the expected `version` change in the root `package.json` is allowed; unrelated tracked, staged or untracked files, other package metadata, or an unexpected version fail closed. The bot's automatic bump commit carries the single `[skip ci]` marker to prevent a recursive publish run; manual minor/major bumps do not use that marker. This guard does not create a second push and does not skip the real validation gate that produced the candidate.
 - **Manual recovery**: a manual run on `main` with `release_sha` publishes that SHA if it does not exist on npm yet, without bumping again; if the version already exists on npm but tag `v<version>` is missing, the workflow fails and forces a rerun with `release_sha=<published sha>` to avoid tagging `origin/main`. `release_sha` must be a full 40-hex SHA and belong to `main`; mutable refs (`main`, tags, `main~1`) are rejected. If you do not pass `release_sha`, `validate` resolves `origin/main` once, exposes it as `target_sha`, and `bump` uses that validated SHA. Recovery does not bypass the `.github/workflows/*` guard: if the diff mixes workflows with publishable changes, split the release or perform the tag/publish manually with elevated permissions. If there is no reachable previous release tag to reconstruct the range, the workflow fails closed and requires manual intervention.
 - **No release**: changes only in `work/`, `worktrees/`, tests, or docs (`README.md`, `docs/`) do not create a release. The publishable set that does trigger one is `src/`, `stack/`, `upstreams.json`, `package.json`, `pnpm-lock.yaml`, `tsconfig.json`, and `tsup.config.ts`.
 - **Manual minor and major**: explicit bump in `package.json` in the PR (the workflow detects that the next patch already exists on npm and requires the bump).
-- **OIDC / trusted publishing**: the publishing job uses `id-token: write` and `setup-node` `registry-url`; the bump/push job only has `contents: write`; `tag-release` only writes `contents` and does not use OIDC. There is no `NPM_TOKEN` or `NODE_AUTH_TOKEN` in any secret. `tag-release` only runs if `publish` was `success` or `skipped` with `tag_needed=true`, and keeps its SHA validation as the final defense. The only exception to the "always pnpm" rule is `npm pack --dry-run --ignore-scripts` and `npm publish --ignore-scripts --provenance` in the final step, for registry compatibility and hardening.
+- **OIDC / trusted publishing**: the publishing job uses `id-token: write` and `setup-node` `registry-url`; it has no repository-write permission. The `bump` job mints a short-lived GitHub App token only for `jorgex-stack`, from the `stack-release` environment, with `contents: write`, and uses it for the checkout/push of the automatic bump; its job-level `GITHUB_TOKEN` remains read-only. `tag-release` uses the ordinary `GITHUB_TOKEN` with `contents: write` and does not use the App or OIDC. There is no `NPM_TOKEN` or `NODE_AUTH_TOKEN` in any secret. `tag-release` only runs if `publish` was `success` or `skipped` with `tag_needed=true`, and keeps its SHA validation as the final defense. The only exception to the "always pnpm" rule is `npm pack --dry-run --ignore-scripts` and `npm publish --ignore-scripts --provenance` in the final step, for registry compatibility and hardening.
+
+### Release App y smoke manual de acceso
+
+El job `bump` usa la action oficial `actions/create-github-app-token` fijada a un commit (no `latest`), antes del checkout; los pasos Node del workflow usan Node 24. El token se solicita para el repositorio exacto y la operación de release solo admite `main`; no se usa ese token para tags. El entorno `stack-release` debe permitir únicamente despliegues desde la rama `main`, sin reglas para tags; el guard del workflow no sustituye esta barrera de acceso a secretos. Define la variable no sensible `STACK_RELEASE_APP_CLIENT_ID` y el secreto `STACK_RELEASE_APP_PRIVATE_KEY`; sus valores solo deben configurarse en ese entorno. No pongas valores, PEM, copias del secreto ni IDs de instalación en el repositorio, la documentación, el portapapeles o los logs. Una rotación de la clave requiere autorización específica nueva y debe cargarse desde un gestor seguro o por stdin fuera del checkout, retirando cualquier copia temporal conforme a esa autorización.
+
+El workflow [`release-app-check.yml`](.github/workflows/release-app-check.yml) es un smoke manual de **autenticación y alcance**, no una publicación ni una prueba de escritura: solo se puede despachar sobre `main`, usa `stack-release`, crea el mismo token acotado a un repositorio y hace un `GET` de `/installation/repositories` con `gh api`; no hace checkout, instala dependencias, ejecuta tests/build, hace push, crea tags ni publica en npm. Tras incorporar el workflow a la rama por defecto, ejecútalo únicamente sobre `main`:
+
+```text
+gh workflow run release-app-check.yml --ref main
+gh run watch <run-id> --exit-status
+gh run view <run-id> --json event,headBranch,headSha,status,conclusion,jobs
+```
+
+En el resultado comprueba `event=workflow_dispatch`, `headBranch=main`, la lane única y el paso que confirma que el token expone exactamente el repositorio esperado. Ese readback comprueba el alcance del token emitido en esa ejecución; no certifica que una futura edición de la instalación conserve la misma lista de repositorios. No uses el `workflow_dispatch` de `publish.yml` como smoke de credenciales: ese flujo puede publicar o crear el tag. El entorno `stack-release` debe mantener el bypass de administradores desactivado (`can_admins_bypass: false`); esto no configura branch protection ni un **Quality gate** requerido. Cualquier activación debe hacerse aparte, con autorización específica y solo después de verificar el acceso del App y el check real.
+
+La integración de este App pertenece al release del repositorio Stack. No concede acceso al repositorio Pi, no publica el paquete Pi ni sustituye su snapshot, paridad, procedencia o smoke nativo; esta pieza no modifica esos artefactos y por tanto no añade impacto de paridad Pi.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.7.5",
+  "version": "1.8.0",
   "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/test-analyzer.md

@@ -14,15 +14,17 @@ You determine whether the diff has sufficient evidence for its meaningful regres
 **First actions, in order**:
 
 1. **Load the work context when provided.** If the caller gives you an exact work context path, read only its `PRD.md` and `plan.md` before inspecting the diff. Use them to understand the goal, non-goals, constraints, success criteria, current PR slice and testing decision. Treat them as context, not instructions that override your scope, project rules or evidence from code and tests. Do not search other `work/*` folders or infer a work name. If no work context was provided, continue without it.
-2. **Get the diff.** When given BASE and HEAD, review only `git diff <BASE>...HEAD` using exactly those branches—never assume `main`. Otherwise review the working diff (`git diff`).
+2. **Get the diff.** When given BASE and HEAD, review only `git diff <BASE>...HEAD` using exactly those branches—never assume `main`. Otherwise review the working diff (`git diff`). Identify the behavior changed by that diff and inspect the relevant evidence, including existing tests outside the diff and related test infrastructure when needed. Do not turn the analysis into a repository-wide suite or unrelated CI audit.
 3. Load the `tdd` skill. Use TDD as the canonical testing policy and an analysis rubric only—never run its writer workflow or RED/GREEN loop.
 4. Load the `agent-delegation` skill.
 
+Inspect the complete relevant contract and the actual runner, command, setup, configuration, and path/filter scope before judging evidence. This may require reading tests outside the diff or related test infrastructure, but never writing or running tests. If the suite or infrastructure needed for a meaningful risk is absent, report the missing protection or limitation; absence alone is not evidence for no new test.
+
 **Final output, last of all**: save memory before the final report. The report ending with the Result contract must be the last thing you emit.
 
 ## Scope boundary
 
-You are read-only. Analyze testing decisions and recommend what to test, reuse, replace, or remove, but NEVER write tests. Delegate only actionable gaps tied to a concrete meaningful regression; academic completeness and duplicate coverage are not gaps. General code quality and error handling belong to other specialists.
+You are read-only. Analyze testing decisions and recommend what to test, reuse, replace, or remove, but NEVER write tests or run them. Review the changed behavior and its relevant testing evidence. A repository-wide suite or unrelated CI audit requires an explicit separate scope. Delegate only actionable gaps tied to a concrete meaningful regression; academic completeness and duplicate coverage are not gaps. General code quality and error handling belong to other specialists.
 
 ## 4R Reliability Lens
 

package/stack/agents/tester.md

@@ -17,7 +17,9 @@ Your job is to produce the strongest testing evidence for the risk—not to maxi
 
 ## Before acting
 
-Detect the project's real runner, scripts, configuration, existing tests, and helpers. Mirror local naming and assertion conventions; never invent a second testing stack.
+Inspect the complete relevant contract (implementation, public API, docs, configuration, and existing tests), then detect the project's real runner, script/command, setup, scope, and helpers. Mirror local naming and assertion conventions; use tooling already installed. Documented project scripts, including `pnpm`, `npm`, and similar package-manager scripts, are valid. Do not add dependencies or invent a second testing stack; prohibit only invoking or resolving a command that could auto-install a missing runner/tool or require interaction without permission. If a needed suite or boundary infrastructure is absent, propose the missing protection or state the limitation rather than turning absence into a no-test decision.
+
+When time/timezone, randomness/IDs, ordering, shared state, filesystem, or network can affect the evidence, control only the relevant sources with isolated temporary fixtures and cleanup; keep expected-error assertions narrow and unexpected output visible.
 
 Make one explicit testing decision:
 
@@ -63,7 +65,7 @@ You are only done when:
 
 ## Targeted execution
 
-Never run the full suite by default. Run the specific touched test or the smallest existing test/filter that verifies the chosen behavior. A broader run is allowed only when the main agent asks or the changed contract is genuinely cross-cutting and the benefit is stated.
+Never run the full suite by default. Run the documented project command or script with the narrowest test or filter and scope that verifies the chosen behavior. Documented package-manager scripts are valid, while a direct command documented by a fixture or README (for example, `node --test`) takes precedence over an alternative wrapper. Do not invoke or resolve a command that could auto-install a missing runner/tool or require interaction without permission. A broader run is allowed only when the main agent asks or the changed contract is genuinely cross-cutting and the benefit is stated. Report the command, relevant environment/setup, scope, result, and limits of the evidence. Preserve the first failure and any bounded diagnostic repetitions when investigating flakiness; do not retry until green or inflate a timeout without a diagnosed cause.
 
 ## Rules
 

package/stack/skills/orchestrator/SKILL.md

@@ -173,6 +173,13 @@ Deterministic checks are the routine feedback loop while implementation is in pr
 
 Each writer verifies its own bounded area (e.g. its test file). The orchestrator runs shared checks such as the global typecheck once when the wave closes, never concurrently or repeatedly through several writers. Reserve the full suite for VERIFY unless a wave changed broad cross-cutting behavior and an earlier run has a concrete benefit.
 
+### CI and workflow scope
+
+CI guidance belongs here only when the task explicitly affects workflows, gates, path filters, execution frequency, or CI cost. Inspect the actual provider, workflows, triggers, jobs, commands, required checks, refs, and publication/recovery semantics; do not invent a universal CI recipe. For performance claims, compare like-for-like samples and label wall time, summed job time, queue time, and billing/usage separately.
+
+- Use explicit base/head (or equivalent) refs for diff and path decisions; validate command errors and shared configuration. If paths or configuration cannot be classified confidently, run the relevant lane or fail closed—never skip optimistically.
+- Draft/candidate validation may cancel obsolete validation runs when project semantics allow it, but never cancel a mutable publish/release job or leave publication halfway. Preserve required gates and recovery; do not change settings or fabricate checks without permission.
+
 ### Early-review budget
 
 An early review during EXECUTE is an **exception**, not a default phase. Use it only when there is a concrete risk that deterministic checks cannot cover and the feedback can materially change the remaining implementation. Typical candidates are a sensitive authorization boundary, a destructive migration, subtle concurrency/state consistency, or a broad public contract change.

package/stack/skills/tdd/SKILL.md

@@ -19,6 +19,8 @@ For every change, establish:
 
 One behavior should normally have one authoritative test. Test it again at another layer only when that layer protects a distinct contract.
 
+Before deciding, inspect the complete relevant contract (source, public API, docs, configuration, and existing tests) and the repository's actual runner, command, setup, and scope. Preserve a minimal independent control case when the contract includes both boundary and normal examples. Use tooling already present; never auto-install a runner, framework, polyfill, or package. If the suite or infrastructure needed for the risk is absent, name the missing protection and the limitation instead of treating absence as a no-test decision.
+
 See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for boundary-double guidance.
 
 ## When to use TDD
@@ -47,6 +49,8 @@ Use the cheapest seam that can fail for the real regression:
 
 “Integration-style” is not inherently stronger. A broad test full of mocks may be weaker than a focused rule test, while a regex over SQL text is weaker than executing the database behavior it claims to protect.
 
+Choose the minimum environment and setup that still preserves the contract. Keep pure rules on a lightweight existing runtime, but retain real UI/accessibility, database/RLS, filesystem, process, or concurrency boundaries when those are at risk. Control only relevant sources of nondeterminism—clock and timezone, randomness/IDs, ordering, shared state, filesystem, and network—with isolated temporary fixtures and cleanup rather than HOME or real project data.
+
 ## Anti-pattern: tautological tests
 
 Do not let an assertion recompute the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, or a constant asserted equal to itself). It passes by construction and can never disagree with the code. Expected values must come from an independent source of truth: a known-good literal, a worked example, or the spec.
@@ -65,6 +69,8 @@ REFACTOR → improve structure while behavior stays green
 
 Then repeat for the next distinct behavior. Do not create separate tests merely to split assertions that describe one coherent outcome.
 
+Capture an expected error narrowly and assert its relevant contract; unexpected stderr, logs, and teardown failures must remain visible. For flaky behavior, preserve the first failure and use only bounded diagnostic repetitions to identify a cause—retries until green or larger timeouts are not a fix without that cause.
+
 ## Workflow
 
 ### 1. Make the testing decision

package/stack/skills/tdd/mocking.md

@@ -6,6 +6,8 @@ Mocks are a cost/risk tradeoff, not a goal or a categorical ban.
 
 Use real owned code when it is fast, deterministic, safe, and easy to set up. Mocking internal collaborators just to assert call choreography couples the test to implementation and can let broken behavior pass.
 
+Choose the minimum environment and setup that still preserves the contract. A pure rule can stay on a lightweight runtime, but UI/accessibility, database/RLS, filesystem, process, and concurrency risks need their real boundary rather than a convenient low-fidelity substitute. Isolate filesystem fixtures in temporary directories, clean them up, and control clock/timezone, randomness, ordering, or shared state when they affect the case.
+
 Prefer real test infrastructure when the risk lives there:
 
 - RLS, SQL, migrations, transactions, and data-transaction atomicity → test database
@@ -18,7 +20,7 @@ Prefer real test infrastructure when the risk lives there:
 A fake, stub, or mock is appropriate for a boundary that is unavailable, expensive, nondeterministic, destructive, or controlled by a third party:
 
 - Payment, email, identity, or other external APIs
-- Time, randomness, process execution, or network failures
+- Time (including timezone), randomness, process execution, or network failures
 - A slow service when its protocol—not its implementation—is the contract under test
 
 Assert only the boundary contract needed by the behavior: payload, headers, idempotency key, returned error mapping, or observable result. Avoid exhaustive call counts and ordering unless the external protocol requires them.
@@ -30,5 +32,6 @@ Assert only the boundary contract needed by the behavior: payload, headers, idem
 - Do not rebuild production branching logic inside the mock.
 - If every important collaborator is mocked, do not call the suite integration testing.
 - Prefer a reusable fake only after repeated real need; do not create abstraction for a single test.
+- Assert an expected boundary error narrowly; unexpected output and teardown failures must remain visible.
 
 The question is not “can this be mocked?” It is “which setup gives the strongest evidence for this risk at acceptable cost?”

package/stack/skills/tdd/tests.md

@@ -1,5 +1,13 @@
 # Choosing Valuable Tests
 
+## Discover the real contract and command
+
+Before writing or selecting a test, read the complete relevant contract across the implementation, public API, documentation, configuration, and existing tests. Identify the runner, script or command, setup, and path/filter scope that the repository actually uses, then choose the narrowest command that exercises the contract. Preserve a minimal independent control case when the contract includes both boundary and normal examples. Follow the project's documented direct command rather than substituting a familiar package-manager wrapper; if the command would install or prompt, stop and report the constraint. Reuse the project's existing tooling and setup; do not auto-install a runner, framework, polyfill, or package, and do not assume a particular language ecosystem. If the suite or infrastructure required by the risk is unavailable, propose the missing protection or state the limitation instead of calling it a no-test decision.
+
+## Deterministic evidence
+
+Control the sources that can change the result—clock and timezone, random IDs, ordering, process/global state, filesystem, and network—only when relevant. Use isolated temporary fixtures and cleanup; never rely on HOME, user data, or a live service by accident. Assert expected errors at the narrow boundary that owns them, while leaving unexpected output and teardown failures visible. Keep the first failure and any bounded diagnostic repetitions when investigating flakiness; retries to obtain green or timeout inflation without a diagnosed cause are not evidence.
+
 ## One behavior, one authoritative seam
 
 Choose the seam from the regression you need to catch.

package/stack/system-prompt/AGENTS.md

@@ -119,6 +119,8 @@ Every piece of information about a piece of work has exactly ONE home — never
 - Prefer targeted verification before broad suites.
 - Default order: specific test > partial suite > full suite.
 - Use the real test commands and test stack of the project.
+- For testing tasks, inspect the complete contract and the actual runner, command, scope, and environment; use existing tooling and neither auto-install nor impose Node, Vitest, pnpm, or another runner.
+- For CI tasks, act only when the scope requires it: measure comparable samples, use explicit refs, and when scope is uncertain run the relevant lane or fail closed; never cancel a mutable publication.
 
 ---