jorgex-stack 1.9.2 → 1.9.4

package/README.md

@@ -6,7 +6,7 @@ Portable multi-agent harness: one configuration source — 15 agents, 18 skills,
 
 ## Skills: release snapshot and supply chain
 
-The 1.9.0 minor release carries a fixed **18-skill snapshot**: **6 stack-owned** skills and **12 vendored** skills. Runtime adapters execute only the local copies committed under `stack/skills`; they do not fetch, install, or execute upstream content at runtime.
+The 1.9.2 release carries a fixed **18-skill snapshot**: **6 stack-owned** skills and **12 vendored** skills. Runtime adapters execute only the local copies committed under `stack/skills`; they do not fetch, install, or execute upstream content at runtime.
 
 | Set | Skills |
 | --- | --- |
@@ -106,21 +106,25 @@ Programmatic mode does **not** provide:
 
 ### Pi runtime
 
-Pi combines the frozen **snapshot v2** package with a Stack-owned shared projection. This PR03 candidate targets the exact published package **`jorgex-pi@0.8.0`** and keeps Pi out of the adapter/component manifest and model map. PR03 pins that candidate in `src/lib/pi-runtime.ts` without changing `package.json`; the published Stack 1.9.0 release still recognizes `npm:jorgex-pi@0.7.0`, so this section does not claim that `main` or an end-user installation has consumed Pi 0.8.0.
+Pi combines the frozen **snapshot v2** package with a Stack-owned shared projection. The current published Stack `1.9.3` still recognizes the outgoing exact package **`jorgex-pi@0.8.0`**. This checkout carries the next production candidate **`jorgex-pi@0.8.3`**; its Stack release is not published yet, so no future Stack version is named here.
+
+The following command set is retained from the historical published Stack `1.9.2`; it is not a command set for the unpublished candidate release.
 
 ```bash
-pnpm dlx jorgex-stack install --agents pi
-pnpm dlx jorgex-stack doctor --agents pi
-pnpm dlx jorgex-stack models --agents pi
-pnpm dlx jorgex-stack sync --agents pi
-pnpm dlx jorgex-stack uninstall --agents pi
+pnpm dlx jorgex-stack@1.9.2 install --agents pi
+pnpm dlx jorgex-stack@1.9.2 doctor --agents pi
+pnpm dlx jorgex-stack@1.9.2 models --agents pi
+pnpm dlx jorgex-stack@1.9.2 sync --agents pi
+pnpm dlx jorgex-stack@1.9.2 uninstall --agents pi
 ```
 
-Stack downloads the frozen registry tarball, verifies its exact size plus SHA-256/SHA-512, backs up Pi's `settings.json`, and only then asks Pi to install that local file. For `0.8.0`, the frozen tarball is `89128340` bytes; the URL is derived from the version and the authoritative size/SHA-256/SHA-512 pin remains in `src/lib/pi-runtime.ts` rather than being duplicated here. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. After the package is healthy, Stack projects the shared resources into Pi: marked `jorgex:system-prompt` and `jorgex:engram-protocol` sections in `~/.pi/agent/AGENTS.md`, canonical skills under `~/.agents/skills`, and `~/.pi/agent/prompts/lean-audit.md`. When the managed Playwright preference is active, the projection also adds or removes the marked `jorgex:browser` section dynamically. The Pi-only `install --agents pi --playwright` flow installs and persists that Playwright capability just like the other harnesses. Chrome DevTools MCP and Context7 remain outside the Pi scope. The managed Pi package entry is the exact object `{ "source": "npm:jorgex-pi@0.8.0", "skills": [], "prompts": [] }`; filters are applied only after this projection exists, so the package does not duplicate shared resources. Package ownership is recorded separately in `~/.jorgex-stack/pi-receipt.json`; projection ownership is recorded in `~/.jorgex-stack/pi-projection-receipt.json`. Both receipts are scope-bound and fail closed for manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state.
+Stack downloads the frozen registry tarball, verifies its exact size plus SHA-256/SHA-512, backs up Pi's `settings.json`, and only then asks Pi to install that local file. For the outgoing `0.8.0` pin, the frozen tarball is `89128340` bytes; the URL is derived from the version and the authoritative integrity pin remains in `src/lib/pi-runtime.ts`. The new candidate is `jorgex-pi@0.8.3`, with `89129618` bytes, release provenance commit `0a35c283fe30a9fed87da3cedc00bab97163e68b`, and parity source `fac3ba828c20134858e2a9aa1e68b920270f7b5a`; these values are sourced from the runtime candidate, its test fixture, and the verified public-artifact evidence. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. After the package is healthy, Stack projects the shared resources into Pi: marked `jorgex:system-prompt` and `jorgex:engram-protocol` sections in `~/.pi/agent/AGENTS.md`, canonical skills under `~/.agents/skills`, and `~/.pi/agent/prompts/lean-audit.md`. When the managed Playwright preference is active, the projection also adds or removes the marked `jorgex:browser` section dynamically. The Pi-only `install --agents pi --playwright` flow installs and persists that Playwright capability just like the other harnesses. Chrome DevTools MCP and Context7 remain outside the Pi scope. The managed Pi package entry is the exact object `{ "source": "npm:jorgex-pi@0.8.3", "skills": [], "prompts": [] }`; filters are applied only after this projection exists, so the package does not duplicate shared resources. Package ownership is recorded separately in `~/.jorgex-stack/pi-receipt.json`; projection ownership is recorded in `~/.jorgex-stack/pi-projection-receipt.json`. Both receipts are scope-bound and fail closed for manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state.
+
+Historically, the published Pi 0.8.0 direct-package snapshot added `work-audit`: the snapshot grew from **17 to 18 skill trees** (96 to 97 files), and the active runtime allowlist grew from **16 to 17 skills**. `playwright-cli` remains in the snapshot but inactive because browser automation is a separate opt-in integration. The 0.8.3 candidate preserves that work-audit introduction.
 
-The published Pi 0.8.0 direct-package snapshot adds `work-audit`: the snapshot grows from **17 to 18 skill trees** (96 to 97 files), and the active runtime allowlist grows from **16 to 17 skills**. `playwright-cli` remains in the snapshot but inactive because browser automation is a separate opt-in integration.
+The published artifact has two separate provenance anchors. The local size/SHA-256/SHA-512 checks bind the downloaded bytes to Stack's accepted candidate; they are checks within that checkout, not independent trust roots. npm's external provenance/attestation is outside Stack runtime verification, and `provenance.commit` is informative unless that external attestation is independently verified.
 
-The published artifact has two separate provenance anchors: the release checkout and tarball producer is `9f999747df3e335947a61d38e581555367973b09` (`main`, release `0.8.0`); and the Stack parity source is `11e7666ea4e40bde1de8bc434610747eb797ab9c`. Registry metadata has no `gitHead`; README does not invent a separate source identity, attestation or signature.
+The outgoing published artifact records two distinct commit identities: the release checkout and tarball producer is `9f999747df3e335947a61d38e581555367973b09` (`main`, release `0.8.0`); and the Stack parity source is `11e7666ea4e40bde1de8bc434610747eb797ab9c`. For the new candidate, the verified Pi release checkout is `0a35c283fe30a9fed87da3cedc00bab97163e68b` and the parity source is `fac3ba828c20134858e2a9aa1e68b920270f7b5a`. Registry metadata has no `gitHead`; README does not invent a separate source identity, attestation or signature.
 
 Install, sync and uninstall back up every managed file before changing it and are idempotent. `doctor` reports package and projection drift without repairing it. Uninstall removes only receipt-owned package/projection state, retains shared files also owned by another runtime, and preserves user content outside marked sections. Engram remains user-owned and is never removed; the receipts only carry the verified executable hand-off required by the package.
 
@@ -128,9 +132,9 @@ The package owns Pi's native primary-model projection: `openai-codex/gpt-5.6-sol
 
 Engram remains mandatory and user-owned. An existing binary is preserved. Interactive install may offer the native `brew`/`go`/release channel with explicit confirmation; `--yes` and non-TTY installs fail with a remedy when Engram is absent. The database and memories are never updated or deleted, and uninstall never deletes the Engram binary. Under `--target-dir`, Stack accepts only `<target>/bin/engram`, isolates Pi/Home/XDG/AppData/temp/npm-cache paths inside the target, and never consults the host Engram or Pi configuration.
 
-The transition from `jorgex-pi@0.7.0` to `jorgex-pi@0.8.0` is not in-place. Each Stack release recognizes only the Pi receipt for its exact pin. The published Stack **`jorgex-stack@1.9.0`** is the corroborated release that still recognizes `npm:jorgex-pi@0.7.0`. PR03 does not change `package.json`; after the merge, the workflow will publish the first free patch in `1.9.x`, expected to be `1.9.1`. T15 must verify the final published version and its recognition of `npm:jorgex-pi@0.8.0` before it is used for a real installation. Use exact versions, never `latest`, and never edit receipts or hashes or delete `HOME`, Engram, or another runtime's projection to force trust. The examples are in `docs/references/pi-runtime.md`; they are documentation, not commands executed by this adoption.
+The published Stack `1.9.3` recognizes the outgoing exact Pi receipt for `npm:jorgex-pi@0.8.0`. This checkout's production candidate is `npm:jorgex-pi@0.8.3`, but the corresponding new Stack release is not published yet; use exact versions, never `latest`, and never edit receipts or hashes or delete `HOME`, Engram, or another runtime's projection to force trust. The historical rollback examples are in [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
 
-The 24-hour npm maturity rule applies only to real managed installation or consumption of the new Pi package. Development, PR validation, merge and Stack publication may proceed immediately against the exact verified artifact; installing it on a real user scope before 24 hours requires Jorge's explicit exception.
+Stack 1.9.3 is the verified published Stack release. The new Pi 0.8.3 artifact has independently verified public registry bytes, but its adopting Stack release still requires post-merge publication and public npm readback before a new Stack version or transition command is documented. The 24-hour managed-consumption maturity rule applies only to real installation or consumption of the new Pi package; development, PR validation, merge and Stack publication may proceed immediately. Installing it on a real user scope before 24 hours requires Jorge's explicit exception.
 
 `update --agents pi` only runs the Pi package lifecycle; it does not enter the global Stack updater. `update --check --agents pi` is a read-only Pi doctor. Uninstall runs package cleanup, backs up Pi's settings before removal, removes only the exact receipt-owned package after verifying absence, and preserves all companion/user state. Full behavior, failure states and troubleshooting are in [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
 
@@ -226,6 +230,7 @@ El preflight condiciona únicamente la preparación de toolchain, la instalació
 - **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.
+- **Rejected rerun recovery**: if a run is rejected because it is a rerun (GITHUB_RUN_ATTEMPT), do not rerun that execution. Start a new `workflow_dispatch` on `main` with `release_sha` set to the accepted/published SHA that still needs publication or tagging; the new workflow validates that immutable SHA before mutating anything.
 - **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`; 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.

package/dist/cli.js

@@ -5142,16 +5142,16 @@ import { createHash } from "crypto";
 var PI_RUNTIME_CANDIDATE = {
   package: {
     name: "jorgex-pi",
-    version: "0.8.0",
-    source: "npm:jorgex-pi@0.8.0"
+    version: "0.8.3",
+    source: "npm:jorgex-pi@0.8.3"
   },
   provenance: {
-    commit: "9f999747df3e335947a61d38e581555367973b09"
+    commit: "0a35c283fe30a9fed87da3cedc00bab97163e68b"
   },
   tarball: {
-    bytes: 89128340,
-    sha256: "b001f9dea23669b7211af228df6ea6442bcd90a9a928aa1a47c3e7132966f989",
-    sha512: "a591bf223e2d48ddecc89341253dc0ac41a6f843796c04ca62f47dc7587b3ec9afafdffba63e52fe99f833aec5ac0b34926eaf3c26f2755003bbf8e6891f6bd9"
+    bytes: 89129618,
+    sha256: "4dfe5aed6ad3043b285d4d171656934708df159846634712a88f947ca8334ef4",
+    sha512: "36f958cb2edcb2ce22e28c59f32ddcb976b889a37cba3637e89478261ddc05d3a9cf1001d29a6aca30a92d935cb07b50243c4d3eca783ed8e580bf15bb3d07aa"
   },
   pi: {
     testedVersions: ["0.84.2"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jorgex-stack",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "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/skills/orchestrator/SKILL.md

@@ -83,6 +83,7 @@ If the work is large enough to benefit from explicit vertical slices, use the `t
 - One task = one agent = one scope.
 - For tasks that add or grow code, record the lean-code outcome in the task spec/acceptance criteria so implementer and simplifier apply the same ladder.
 - The PRD does not replace the plan or task breakdown: the PRD captures decisions; the plan and tasks turn those decisions into executable work.
+- **Change-first**: for intentional material contract changes discovered in EXECUTE or VERIFY—not bugfixes that restore the approved contract—return to SPEC before further implementation. Update the PRD first, then propagate it to the plan, task specs, `SC-*` success criteria and testing decisions; rerun PRE until `clean`, obtain human approval of the delta, then resume EXECUTE and repeat VERIFY.
 - Materialize the plan per the Work state rules: `work/{name}/plan.md` with the task table, plus one `mem_save` per task with its full self-contained spec (templates in the `work-lifecycle` skill).
 - Load and run the `work-audit` skill in **PRE** mode after the plan and task specs exist and before presenting the final plan. Pass the exact active `work/{name}` path and the exact PR/checkpoint scope; never infer either from the branch or scan other work folders. PRE is read-only: during audit remediation you are the only writer of active work artifacts. Route every finding to its owner artifact, correct it, and rerun PRE until it reports `clean`.
 - An unresolved `[NEEDS CLARIFICATION: ...]` marker blocks PRE. Return to SPEC and resolve the ambiguity with the user only when existing context cannot answer it; never approve or execute a plan while PRE is not clean.
@@ -196,6 +197,7 @@ An early review during EXECUTE is an **exception**, not a default phase. Use it
 
 - Run the minimum verification that is sufficient.
 - Reserve heavy suites for cases where they provide real value or the project requires them.
+- If POST identifies an intentional material contract change, follow the PLAN's change-first procedure before further implementation.
 - Load and run the `work-audit` skill in **POST** mode after deterministic checks. Pass the exact active `work/{name}` path and the exact current checkpoint scope. POST is read-only and must report `converged`; when it reports `gaps`, during audit remediation you are the only writer of active work artifacts: add normal plan tasks and Engram specs when needed, return to the phase that owns each gap, and rerun POST after the fixes.
 - Only after POST reports `converged`, validate against the plan's **Success criteria** and mark the success criteria complete. Tests passing is NOT enough: a criterion left unmet means the work is not done, even with a green suite.
 - Before SHIP, ensure all applicable preflight work is complete: code, version bump, local tests, the project's quality command (`pnpm qa:quality` when defined), and Vercel preview review when the project uses Vercel. React Doctor is manual/local, never assumed to be a GitHub Actions gate.

package/stack/skills/work-audit/SKILL.md

@@ -28,6 +28,7 @@ Run after the plan and task specs exist, before presenting the final plan for ap
 Check:
 
 1. No unresolved `[NEEDS CLARIFICATION: ...]` marker remains.
+   - Report a latent material semantic ambiguity as a gap only when plausible interpretations differ materially in observable behavior, scope, success criteria or testing. Only low-impact implementation preferences, defaults, wording and paths are excluded from gaps or clarification; material alternatives still block.
 2. Success criteria use unique IDs such as `SC-01`; report duplicate or malformed `SC-*` IDs.
 3. Every SC is verifiable and has task coverage in the plan table.
 4. Every task references known SCs and has one agent, one bounded scope, affected files, dependencies and a wave consistent with those dependencies.
@@ -49,13 +50,14 @@ Check:
 1. Every planned task for the checkpoint has the expected status and bounded outcome.
 2. Every in-scope SC has concrete evidence in its canonical checkpoint: command/setup, scope, result and relevant limits.
 3. The implementation diff and observed behavior stay within the approved PRD, plan and task scopes.
+   - POST cannot legitimize scope changes retroactively. For intentional material contract changes, send scope drift to SPEC through change-first. Defects or bugfixes restoring the approved contract return to EXECUTE.
 4. Tests, typecheck/build, manual checks and external gates are not over-claimed; missing or incomplete execution remains explicit.
 5. No accepted requirement, edge case, testing decision, documentation change or cross-repo contract assigned to the current checkpoint is left without implementation or evidence. Future checkpoints remain out of scope.
 
 POST verdicts:
 
 - `converged` — the available evidence satisfies the approved contract. This does not replace tests, human review, configured Quality Gates or manual validation when applicable.
-- `gaps` — return actionable findings to the orchestrator; implementation must return to EXECUTE and POST must run again.
+- `gaps` — return actionable findings to the orchestrator and route each to its owning phase; never send every gap unconditionally to EXECUTE. Rerun POST after the fix.
 
 ## Read-only boundary