gemstack-ai 1.1.2 → 1.3.0

package/.agents/skills/gemstack-plan/SKILL.md

@@ -17,5 +17,6 @@ Invocado mediante `/plan`.
 5. Detalla el stack y llena la tabla "Complexity Tracking" SÓLO si rompiste alguna regla de la constitución y necesitas justificarlo.
 6. Opcionalmente, genera los entregables satélites: `data-model.md`, `contracts/` (para APIs/Interfaces), y `quickstart.md`.
 7. **Herencia y Contratos Aditivos (Upgrade A)**: PLAN hereda automáticamente los contratos declarados en `spec.md`. No contradigas ni alteres los contratos congelados heredados; si requieres contratos técnicos adicionales, decláralos de forma compatible y aditiva en el bloque ````gemstack-contracts ```` de `plan.md`.
-8. Pide aprobación al usuario antes de permitir la ejecución de `/tasks`.
+8. **Vinculación Física de Pruebas y Gates (Upgrade B)**: Define en `plan.md` los bloques canónicos ````gemstack-test-bindings ```` (asociando cada ID de prueba a un archivo físico y runner) y ````gemstack-closure-gates ```` (especificando scripts de package.json obligatorios).
+9. Pide aprobación al usuario antes de permitir la ejecución de `/tasks`.
 

package/.agents/skills/gemstack-qa/SKILL.md

@@ -15,3 +15,6 @@ Invocado mediante `/qa` o `/qa-only`.
 3. Si la aplicación es visual, recomienda `/browser` o correr tests de Playwright para verificar manualmente la UI.
 4. Genera un breve reporte indicando si cada Criterio pasó o falló.
 
+
+5. **Recolección Mecánica de Evidencias (Upgrade B)**: Ejecuta `node src/cli.js collect` para ejecutar los runners de pruebas, gates y reconciliar la matriz mecánica generando `specs/[nombre-feature]/closure.json`.
+6. Valida que la evidencia esté fresca y en modo lectura con `node src/cli.js verify`.

package/.agents/skills/gemstack-ship/SKILL.md

@@ -12,7 +12,11 @@ Invocado mediante `/ship`.
 ## Proceso:
 1. Verifica revisión (`/review`) y validación (`/qa`).
 2. Confirma validación de seguridad (`/cso`).
-3. Comprueba si los specs se cumplieron.
+3. **Validación de Evidencia Mecánica de Cierre (Upgrade B)**:
+   - Comprueba que exista `specs/[nombre-feature]/closure.json`.
+   - Confirma que el estado sea `VERIFIED` o `VERIFIED_WITH_EXCEPTIONS`.
+   - Bloquea el ship si el estado es `STALE`, `BLOCKED`, o si falta el archivo (a menos que la feature opere en modo LEGACY).
+   - Ejecuta `node src/cli.js ship` para validar compuertas y transicionar el ciclo de vida.
 4. Genera un PR summary si se pide.
 5. NO hagas push, merge o deploy sin aprobación explícita.
 6. Sugiere ejecutar `/handoff` para documentar la entrega en la memoria del proyecto.

package/.agents/skills/gemstack-spec/SKILL.md

@@ -20,6 +20,7 @@ Eres un Product Manager técnico. Tu objetivo es convertir ideas vagas en requis
 5. **CERO SUPOSICIONES**: Si el usuario omitió detalles, NO adivines. Usa el marcador `[NEEDS CLARIFICATION: tu duda]` en el documento.
 6. No describas implementación técnica (nada de stacks, bases de datos o APIs). Concéntrate estrictamente en el "Qué" y "Por qué".
 7. **Contratos Arquitectónicos Congelados (Upgrade A)**: Si la funcionalidad implica decisiones estructurales críticas (estados enum, tuplas de identidad, reglas de procedencia, invariantes booleanas, límites de roadmap o límites boundary), decláralos explícitamente en el bloque canónico ````gemstack-contracts ````. Congela solo decisiones materiales, no texto arbitrario.
-8. Actualiza el archivo `.gemstack/state.json` para reflejar la rama activa y fase: `{"active_spec": "specs/[nombre-feature]/", "current_phase": "spec", "last_update": "<timestamp>"}`.
-9. Una vez finalizado, indica al usuario que puede revisar la especificación y, tras resolver las dudas, ejecutar `/plan`.
+8. **Matriz Mecánica de Pruebas (Upgrade B)**: Declara la matriz canónica en el bloque ````gemstack-test-matrix ```` de `spec.md`, asignando IDs canónicos estables `TEST-[FEATURE]-[CAT][NUM]`, capas y compuertas (REQUIRED | SUPPLEMENTAL).
+9. Actualiza el archivo `.gemstack/state.json` para reflejar la rama activa y fase: `{"active_spec": "specs/[nombre-feature]/", "current_phase": "spec", "last_update": "<timestamp>"}`.
+10. Una vez finalizado, indica al usuario que puede revisar la especificación y, tras resolver las dudas, ejecutar `/plan`.
 

package/.agents/skills/gemstack-tasks/SKILL.md

@@ -13,7 +13,8 @@ Invocado mediante `/tasks`.
 1. Lee `specs/[nombre-feature]/plan.md` y, si existen, `data-model.md` y la carpeta `contracts/`.
 2. Convierte los contratos, entidades y el plan en una lista estricta de ejecución en `specs/[nombre-feature]/tasks.md` usando la plantilla `specs/templates/tasks.md`.
 3. **Herencia de Contratos (Upgrade A)**: TASKS hereda automáticamente los contratos consolidados de SPEC y PLAN. No se requiere declarar un bloque de contratos propio salvo que se agreguen contratos operacionales específicos de tareas.
-4. Aplica Test-First: Las tareas de escribir pruebas (y validarlas) deben ir ANTES que la implementación de código.
-5. Usa el marcador `[P]` para tareas independientes que se puedan paralelizar.
-6. Ofrece al usuario comenzar automáticamente con la primera tarea o delegar a subagentes paralelos si hay múltiples `[P]`.
+4. **Trazabilidad TASK -> TEST (Upgrade B)**: Para cada tarea, incluye comentarios de metadatos `<!-- gemstack:validation_required=true|false -->`, `<!-- gemstack:tests=... -->`, y `<!-- gemstack:files=... -->`, asegurando que todas las pruebas canónicas requeridas estén mapeadas a al menos una tarea de implementación.
+5. Aplica Test-First: Las tareas de escribir pruebas (y validarlas) deben ir ANTES que la implementación de código.
+6. Usa el marcador `[P]` para tareas independientes que se puedan paralelizar.
+7. Ofrece al usuario comenzar automáticamente con la primera tarea o delegar a subagentes paralelos si hay múltiples `[P]`.
 

package/.gemstack/state.json

@@ -2,18 +2,17 @@
   "version": "0.1",
   "current_phase": "shipped",
   "status": "SHIPPED",
-  "stop_reason": "UPGRADE_A_SHIPPED_DONE",
+  "stop_reason": "UPGRADE_C_SHIPPED_DONE",
   "active_spec": null,
   "completed_phases": [
     "spec",
     "plan",
-    "tasks",
-    "implement"
+    "tasks"
   ],
   "phase_hashes": {
-    "spec": "f5d423eaf508b06b663b39f467fba1d9ceff6db21f01e427500ad739a90c5be8",
-    "plan": "1ce0e58863427905022a6294f8683b9f508d72b171379c78807db19862c75004",
-    "tasks": "dfad2484ad112e26ef906ea851b12cf6ea090d6faf244a6fbd2650baee8e0d98"
+    "spec": "9241b9e992f687e80ecef388c79731ece7af9aa75ba989dc8f0b1e9b855f7914",
+    "plan": "6a2e29e9aeda266a71ab435fa09bca3b18521835a69f6020cd8d9f135643e3aa",
+    "tasks": "1697c32a1f6596f317491df68cd1b161e5c77fbbddc74ce3f1e6e00a42619249"
   },
   "consistency": {
     "status": "PASS",
@@ -24,6 +23,6 @@
     "freeze": false,
     "allowed_paths": []
   },
-  "last_update": "2026-09-11T09:01:18.769Z",
-  "last_completed_feature": "specs/006-architecture-consistency-engine/"
+  "last_update": "2026-09-11T17:38:04.916Z",
+  "last_completed_feature": "specs/008-cost-provider-safety-gates"
 }

package/CHANGELOG.md

@@ -2,6 +2,81 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.3.0] - 2026-09-11
+
+### Added
+- **Cost & Provider Safety Gates (Upgrade C)**: Deterministic, fail-closed safety and cost verification framework for commercial, external, and AI provider interactions.
+  - `ProviderCapabilityGate`: validates that requested capabilities are declared and supported by the active provider adapter before invocation.
+  - `BillableActionGate`: blocks billable actions unless explicit spending authorization tokens are granted.
+  - Provider Registry: canonical provider directory with declared capability contracts and deterministic rejection of unknown providers.
+  - Cost Ledger (`cost-ledger.json`): auditable schema validating provider cost assumptions, freshness thresholds, and currency units.
+  - Fail-Closed Unknown Cost Policy: unclassified or ambiguous operations are strictly treated as commercial rather than defaulted to free.
+  - Environment Safety Isolation: prevents accidental commercial provider invocations in `test` and `ci` environments even if ambient credentials exist.
+  - Trusted Mock Boundaries: enforces that test mocks execute strictly in memory with zero network escapes.
+  - Re-Entrant Fallback Authorization: secondary fallback providers trigger independent gate re-evaluation before execution.
+  - Verification Purity: guarantees `gemstack verify` executes offline with zero network sockets and zero ledger file mutations.
+- **Context Capsule / Context Compression (Upgrade D)**: Deterministic, auditable, constraint-lossless context compression architecture for cross-session AI continuation.
+  - Deterministic Context Capsule Generation: compiles authoritative sources (`spec.md`, `plan.md`, `tasks.md`, `.gemstack/state.json`, `closure.json`) into `context-capsule.json`.
+  - Constraint-Lossless Compression: 100% of normative `MUST` and `MUST NOT` constraints, frozen contracts, and acceptance signatures survive compression.
+  - Canonical Authority Precedence: authoritative repository sources unconditionally govern over derived capsule claims (`SPEC` > `PLAN` > `TASKS` > implementation).
+  - Provenance & Freshness Hashing: live SHA-256 source digests detect drift or manual tampering immediately (`STALE` / `TAMPERED`).
+  - Strict Secrets Defense: automatic regex and property pattern scanner rejects tokens, API keys, private keys, and `.env` references fail-closed.
+  - Size Budget Enforcement: 32 KB target budget with deterministic 3-tier condensation and 64 KB fail-closed hard limit.
+  - Pure Offline & Atomic Writing: generation and validation execute 100% offline with atomic write semantics (`.tmp` + rename).
+  - Read-Only Verification (Stage 5.2): `gemstack verify` inspects context capsule freshness without disk writes or file mutation.
+  - New CLI Surface: `gemstack context generate`, `gemstack context show`, and `gemstack context verify`.
+  - Progressive Legacy Support: repositories or features lacking capsules operate cleanly with informational notices and zero blockers.
+
+### Changed
+- `gemstack verify` pipeline extended to include Stage 5.2 Context Capsule read-only audit.
+- `package.json` test script updated to explicitly enumerate all 25 physical test suites across Upgrades A, B, C, and D.
+- Closure context resolution (`src/lib/closure-context.js`) incorporates `context-capsule.json` in relevant files hashing.
+
+### Compatibility
+- 100% backward compatible with existing Gemstack repositories and frozen contracts from Upgrades A, B, and C.
+- Zero external runtime npm dependencies added (`package.json` dependencies remain `{}`).
+
+### Validation
+- 20/20 Upgrade C canonical acceptance tests passing (`TEST-COST-A01` through `H01`).
+- 20/20 Upgrade D canonical acceptance tests passing (`TEST-CONTEXT-A01` through `H01`).
+- 85/85 combined canonical acceptance tests passing (25 Upgrade A + 20 Upgrade B + 20 Upgrade C + 20 Upgrade D).
+- 100/100 physical tests passing with 0 failures and 0 regressions.
+- Full CI test matrix (`npm run ci:all`) passing cleanly.
+- `gemstack verify` exit code 0 with 0 errors and 0 open blockers.
+- Context capsule verified: `VALID` and `FRESH` (11,873 bytes < 32 KB budget).
+
+## [v1.2.0] - 2026-09-11
+### Added
+- **Mechanical Test Matrix & Closure Evidence (Upgrade B)**: Full mechanical closure verification framework eliminating false closure and test discovery hallucinations.
+- Canonical fenced `gemstack-test-matrix` blocks in `spec.md` with 20 canonical acceptance test criteria (`TEST-CLOSURE-A01` through `H01`).
+- Deterministic Acceptance Signature (`acceptanceSignature`): SHA-256 digest calculated across all canonical test definitions ensuring immutable acceptance criteria.
+- Bidirectional Task <-> Test Traceability: strict mapping between `tasks.md` validation blocks and canonical acceptance tests.
+- Zero-Shell Test Runner Adapters: safe, cross-platform `node:test` TAP runner adapter with suite container detection (`kind: 'SUITE'` vs `kind: 'TEST'`).
+- Exact Canonical Reconciliation Arithmetic: verifies `canonical_required = canonical_passed + missing`, `physical_executed = canonical_executed + supporting_executed`, and prevents phantoms and orphans.
+- Mutating Evidence Collector (`gemstack collect`): executes bound test files and required `PACKAGE_SCRIPT` gates to produce `specs/<feature>/closure.json`.
+- Dynamic Closure Context Freshness (`closureContextHash`): binds closure evidence to the repository state (clean/dirty git or non-git), phase hashes, test files, and bounded implementation code.
+- Read-Only Closure Gate in `gemstack verify`: stage 5/6 verifies `closure.json` freshness and acceptance criteria without writing or mutating any files on disk.
+- Lifecycle Ship Enforcement (`gemstack ship`): requires status `VERIFIED` in `closure.json` before transitioning feature lifecycle to `SHIPPED`.
+- Progressive `LEGACY` mode support: features lacking test matrix blocks continue without friction or errors.
+
+### Changed
+- `gemstack verify` upgraded to a 6-stage deterministic verification pipeline with zero-mutation read-only verification.
+- `package.json` test script explicitly enumerates all 11 physical test suites for portable cross-platform execution.
+- Agent skills (`gemstack-spec`, `gemstack-plan`, `gemstack-tasks`, `gemstack-qa`, `gemstack-ship`) and templates updated with Upgrade B canonical workflows.
+
+### Compatibility
+- 100% backward compatible with existing Gemstack repositories and Upgrade A contract blocks.
+- Zero external runtime or development npm dependencies added (`package.json` dependencies remain `{}`).
+
+### Validation
+- 22/22 Upgrade B implementation tasks complete (T001–T022).
+- 20/20 canonical P1 acceptance tests passing.
+- 45/45 combined canonical acceptance tests passing (25 Upgrade A + 20 Upgrade B).
+- 53/53 physical tests passing with 0 regressions.
+- `npm test` exit code 0.
+- `gemstack verify` exit code 0 with 0 open blockers.
+- Self-dogfooded on `specs/007-mechanical-test-matrix-closure-evidence/` with closure status `VERIFIED`.
+
 ## [v1.1.2] - 2026-09-11
 ### Fixed
 - Fixed host-dependent normalization of simulated Windows paths in the Architecture Consistency Engine.

package/README.md

@@ -95,6 +95,42 @@ Gemstack mechanically prevents AI agents from silently violating or hallucinatin
 - `gemstack verify` performs strictly read-only verification without mutating or overwriting accepted phase hashes (`VERIFY != FREEZE`).
 - Existing projects without structured contracts automatically run in **LEGACY** mode without breaking.
 
+
+## 🧪 Mechanical Test Matrix & Closure Evidence
+
+Gemstack Upgrade B guarantees that what was planned is what was physically tested:
+- **Canonical Test Matrix**: `spec.md` declares canonical acceptance tests and cryptographic `acceptanceSignature`.
+- **Physical Test Bindings**: `plan.md` maps canonical IDs 1:1 to physical runner test files.
+- **Task Traceability**: `tasks.md` validates that all required canonical tests have implementation tasks.
+- **Safe Runner Adapters**: Direct zero-shell execution of test suites and package script gates.
+- **`gemstack collect`**: Mutating runner that executes tests and atomically writes `specs/<feature>/closure.json`.
+- **`gemstack verify`**: Strictly read-only 6-stage validator verifying evidence freshness against `closureContextHash`.
+- **`gemstack ship`**: Gatekeeper requiring verified evidence before allowing transition to `SHIPPED`.
+- **Git Optionality & Legacy Support**: Works identically on clean Git, dirty Git, and non-Git projects, with graceful legacy fallback.
+
+## 🛡️ Cost & Provider Safety Gates
+
+Gemstack Upgrade C guarantees fail-closed safety for commercial, remote, and AI providers:
+- **`ProviderCapabilityGate`**: Validates provider capability declarations before invocation without network attempts.
+- **`BillableActionGate`**: Enforces strict spending authorization tokens before executing billable operations.
+- **Cost Ledger (`cost-ledger.json`)**: Auditable schema tracking provider cost assumptions, freshness thresholds, and currency units.
+- **Fail-Closed Unknown Cost Policy**: Operations with unclassified or ambiguous costs are strictly blocked.
+- **Environment Safety**: Commercial provider execution is forbidden in `test` and `ci` environments.
+- **Trusted Mock Boundaries**: Test mocks operate strictly in memory with zero network escapes.
+- **Offline Purity**: `gemstack verify` runs 100% offline with zero external network or provider charges.
+
+## 📦 Context Capsule & Compression
+
+Gemstack Upgrade D enables deterministic, constraint-lossless context compression for cross-session continuation:
+- **`gemstack context generate`**: Compiles authoritative specifications, plans, tasks, contracts, and closure evidence into `context-capsule.json`.
+- **Constraint Losslessness**: 100% of normative `MUST`/`MUST NOT` constraints, frozen contracts, and acceptance criteria survive compression.
+- **Authority Precedence**: Authoritative repository artifacts unconditionally override derived capsule claims (`SPEC` > `PLAN` > `TASKS` > implementation).
+- **Drift & Tampering Detection**: Live SHA-256 source hashing flags modified or manually tampered capsules as `STALE`.
+- **Secret Defense**: Fail-closed regex scanning strictly blocks credentials, tokens, private keys, and `.env` data.
+- **Size Budgeting**: 32 KB target budget with deterministic priority condensation and 64 KB fail-closed hard cap.
+- **`gemstack context show`**: Displays human-readable continuation context summary or raw JSON.
+- **`gemstack context verify`**: Read-only validation of context capsule freshness and integrity.
+
 ## 🐝 Advanced Autonomy (The WOW Update)
 
 Gemstack isn't just passive documents; it actively orchestrates agentic capabilities:

package/RELEASE_NOTES.md

@@ -1,5 +1,66 @@
 # Gemstack Release Notes
 
+# Gemstack v1.3.0 — Cost & Provider Safety Gates + Context Capsule
+
+## Highlights
+
+### Upgrade C — Cost & Provider Safety Gates
+- **Deterministic Provider & Capability Validation (`ProviderCapabilityGate`)**: Validates requested provider capabilities ahead of invocation and fail-closes on undeclared or unsupported capabilities without network calls.
+- **Spending Authorization Barrier (`BillableActionGate`)**: Enforces the central invariant "NO PROOF = NO EXECUTION"; commercial or billable actions are strictly blocked unless accompanied by valid explicit spending tokens.
+- **Auditable Cost Ledger (`cost-ledger.json`)**: Machine-readable schema establishing strict freshness dates, provider cost classifications, and zero-secrets immunity.
+- **Fail-Closed Unknown Cost Policy**: Unclassified or unknown operations are never assumed free; they are treated fail-closed as commercial risks.
+- **Environment Safety & CI Isolation**: Prevents accidental commercial provider calls during tests and CI builds regardless of ambient developer credentials.
+- **Trusted Mock Enforcement**: Verifies in-memory mocks remain isolated and fail-closed against external network socket leaks.
+- **Re-Entrant Provider Fallback**: Fallback target providers trigger independent gate re-evaluation before execution.
+- **Verification Purity**: Guarantees `gemstack verify` runs strictly offline with zero provider charges and zero file mutations.
+
+### Upgrade D — Context Capsule / Context Compression
+- **Deterministic Context Compression**: Compiles authoritative specification, plan, tasks, lifecycle, and closure artifacts into compact, machine-readable continuation context (`context-capsule.json`).
+- **Constraint-Lossless Compression**: 100% of normative behavioral constraints (`MUST`, `MUST NOT`), frozen architectural contracts, and acceptance criteria survive compression without semantic loss.
+- **Canonical Authority Precedence**: Authoritative repository artifacts unconditionally govern over derived capsule claims (`SPEC` > `PLAN` > `TASKS` > implementation).
+- **Cryptographic Provenance & Drift Detection**: Live SHA-256 source digests detect artifact modifications or tampering immediately (`STALE` / `TAMPERED`).
+- **Strict Secrets Barrier**: Automated regex scanner blocks credential properties (`apiKey`, `token`, `secret`, `clientSecret`), token patterns (`sk-...`, `AIza...`, `ghp_...`), private keys, and `.env` references.
+- **Deterministic Size Budgeting**: 32 KB target budget with prioritized 3-tier condensation and a 64 KB hard fail-closed limit.
+- **Read-Only Verification (Stage 5.2)**: `gemstack verify` inspects context capsule freshness without modifying or rewriting disk state.
+- **CLI Commands**: `gemstack context generate`, `gemstack context show`, and `gemstack context verify`.
+- **Zero Runtime Dependencies**: Native Node.js standard library implementation (`node:crypto`, `node:fs`, `node:path`, `node:test`).
+
+## Acceptance & Regression Baseline
+- 25 Upgrade A canonical acceptance tests passing (`TEST-CONSISTENCY-A01` through `H02`).
+- 20 Upgrade B canonical acceptance tests passing (`TEST-CLOSURE-A01` through `H01`).
+- 20 Upgrade C canonical acceptance tests passing (`TEST-COST-A01` through `H01`).
+- 20 Upgrade D canonical acceptance tests passing (`TEST-CONTEXT-A01` through `H01`).
+- 85 total canonical acceptance tests passing.
+- 100 total physical tests passing across 25 explicitly enumerated suites.
+- Full CI suite (`npm run ci:all`) passing with 0 warnings and 0 errors.
+- Both Upgrade C and Upgrade D closed with closure status `VERIFIED`.
+
+---
+
+# Gemstack v1.2.0 — Mechanical Test Matrix & Closure Evidence
+
+## Highlights
+- **Mechanical Test Matrix & Closure Verification (Upgrade B)**: Eliminates false closure and test discovery hallucinations by introducing a deterministic verification pipeline from specification to shipment.
+- **Canonical Test Matrix (`gemstack-test-matrix`)**: Explicit acceptance criteria defined in `spec.md` with deterministic `acceptanceSignature` (SHA-256) ensuring acceptance rules are immutable once approved.
+- **Task ↔ Test Traceability**: Explicit bidirectional binding between implementation tasks in `tasks.md` and canonical acceptance tests.
+- **Safe Zero-Shell Runners**: Pure Node.js `node:test` TAP runner adapter with suite container exclusion (`kind: 'SUITE'` vs `kind: 'TEST'`), ensuring TAP headers/containers are never counted as physical tests.
+- **Exact Canonical Reconciliation Arithmetic**: Mechanical validation proving `canonical_required = canonical_passed + missing` and `physical_executed = canonical_executed + supporting_executed` with zero tolerance for phantoms or orphans.
+- **Mutating Collector (`gemstack collect`)**: Executes bound test suites and required `PACKAGE_SCRIPT` gates to produce `specs/<feature>/closure.json`.
+- **Dynamic Closure Context Freshness (`closureContextHash`)**: Cryptographically binds closure evidence to repository state (clean git, dirty git, or non-git), phase hashes, bound test files, and bounded implementation source files.
+- **Read-Only Verification Pipeline (`gemstack verify`)**: Stage 5/6 inspects closure freshness and gate outcomes in memory with 0 disk mutations.
+- **Ship Gatekeeper (`gemstack ship`)**: Strict gate requiring `status: "VERIFIED"` in `closure.json` before transitioning feature lifecycle to `SHIPPED`.
+- **Progressive LEGACY Mode**: Full backward compatibility for features without test matrices or contract blocks.
+- **Zero-Dependency Architecture**: 100% native Node.js standard library implementation with zero third-party production dependencies.
+
+## Acceptance & Regression Baseline
+- 25 Upgrade A canonical acceptance tests passing (`TEST-CONSISTENCY-A01` through `H02`).
+- 20 Upgrade B canonical acceptance tests passing (`TEST-CLOSURE-A01` through `H01`).
+- 45 total canonical acceptance tests passing.
+- 53 total physical tests passing with 0 regressions.
+- 11 physical test suites explicitly enumerated for cross-platform reliability.
+
+---
+
 # Gemstack v1.1.2 — Architecture Consistency & Phase Freezing
 
 ## Recovery Release Note

package/docs/architecture-consistency.md

@@ -130,10 +130,10 @@ Gemstack strictly separates operational state from historical audit trails:
 
 ## 9. Verification Integration (`gemstack verify`)
 
-Architectural consistency is embedded as **Step 4/5** in the unified `gemstack verify` command:
+Architectural consistency is embedded as **Step 4/6** in the unified `gemstack verify` command:
 
 ```text
-[INFO] --- 4/5 Verificación de Consistencia de Arquitectura y Hashes de Fase ---
+[INFO] --- 4/6 Verificación de Consistencia de Arquitectura y Hashes de Fase ---
 [OK] [STRUCTURED] 5 contrato(s) base declarados en spec.md.
 [OK] Hash congelado de spec.md verificado: f5d423eaf508...
 [OK] Hash congelado de plan.md verificado: 1ce0e5886342...
@@ -142,3 +142,15 @@ Architectural consistency is embedded as **Step 4/5** in the unified `gemstack v
 ```
 
 If any contracts contradict, artifacts mutate, or unapproved blockers exist, `gemstack verify` exits with code 1, halting CI/CD pipelines.
+
+---
+
+## 10. Mechanical Test Matrix & Closure Evidence (Upgrade B)
+
+Beyond static contract consistency across phase files, Gemstack Upgrade B validates execution evidence against declared requirements:
+
+- **`acceptanceSignature`**: Full semantic record SHA-256 digest of the canonical test matrix in `spec.md`.
+- **Authoritative Execution**: Native test runners (such as `node:test`) execute bound tests without shell intermediaries. TAP output is parsed to extract executed canonical test tokens.
+- **Reconciliation & Set Equality**: Proves that all declared required canonical tests were physically executed and passed (`PASS + FAIL + SKIP + TODO + CANCELLED == TOTAL_PHYSICAL`). Detects `PHANTOM_TEST` (claimed but unexecuted) and `ORPHAN_TEST` (executed with unregistered canonical ID).
+- **`closureContextHash`**: Deterministic SHA-256 fingerprint binding repository state, phase hashes, test files, implementation files, and gate definitions. Prevents whole-repository scanning while detecting stale evidence.
+- **Progressive Legacy Compatibility**: Specifications lacking a test matrix operate seamlessly in legacy mode with an informational notice, preserving 100% backward compatibility.

package/docs/spec-driven-development.md

@@ -8,3 +8,29 @@ Inspirado en Spec Kit, Gemstack obliga a pensar antes de teclear.
 
 Usa `/specify` para comenzar este ciclo.
 Una vez que el spec esté aprobado por el usuario, usa `/plan` y luego `/tasks`.
+
+
+---
+
+## Mechanical Test Matrix & Closure Evidence (Upgrade B)
+
+Gemstack complements Architecture Consistency with mechanical closure verification:
+
+1. **Test Matrix in Spec (`spec.md`)**:
+   Declared in a ```gemstack-test-matrix``` block. Defines canonical acceptance tests with unique IDs (`TEST-[FEATURE]-[CAT][NUM]`), verification layers (`UNIT`, `INTEGRATION`, `E2E`, `CLI`), and enforcement gates (`REQUIRED`, `SUPPLEMENTAL`). Produces an immutable `acceptanceSignature`.
+
+2. **Physical Test Bindings in Plan (`plan.md`)**:
+   Declared in ```gemstack-test-bindings``` block mapping each canonical test ID 1:1 to a physical runner file (e.g. `tests/example.test.js` with runner `node:test`).
+   Also declares mandatory package script gates in ```gemstack-closure-gates```.
+
+3. **Task Traceability in Tasks (`tasks.md`)**:
+   Implementation tasks declare metadata:
+   `<!-- gemstack:validation_required=true|false -->`
+   `<!-- gemstack:tests=TEST-001,TEST-002 -->`
+   `<!-- gemstack:files=src/module.js,tests/module.test.js -->`
+   Ensures that every required canonical test is bound to at least one implementation task.
+
+4. **Lifecycle: COLLECT vs VERIFY vs SHIP**:
+   - `gemstack collect`: Mutating evidence collector. Executes test runners, evaluates package script gates, reconciles counts, computes `closureContextHash`, and generates feature-local `closure.json`.
+   - `gemstack verify`: Strictly read-only validator (6 stages). Evaluates existing `closure.json` against in-memory fresh `closureContextHash`. Never writes to disk.
+   - `gemstack ship`: Lifecycle gatekeeper. Enforces that `closure.json` is fresh and marked `VERIFIED` (or policy-waived `VERIFIED_WITH_EXCEPTIONS`) before transitioning state to `SHIPPED`.

package/handoff.md

@@ -8,25 +8,40 @@ Evolucionar Gemstack incorporando el feedback de producción real de proyectos a
 4. Comando unificado `gemstack verify` (alias `audit`) para auditoría integral en un solo paso.
 
 ## 2. Estado actual
-- **Upgrade A (Consistency Core & Phase Freezing)**: CERRADO Y LIBERADO como v1.1.0 (`GEMSTACK UPGRADE A SHIPPED / DONE — ARCHITECTURE CLOSED`).
-- 17/17 tareas completadas, 25/25 tests canónicos P1 pasando (33/33 físicos), 0 bloqueadores.
-- Reglas `01-gemstack-core.md`, `02-gemstack-constitution.md`, plantillas y skills actualizados y sincronizados en `template/`.
-- Motor de consistencia integrado en `gemstack verify` (Paso 4/5).
+- **Upgrade A (Consistency Core & Phase Freezing)**: CERRADO Y PUBLICADO OFICIALMENTE en `v1.1.2`.
+- **Upgrade B (Mechanical Test Matrix & Closure Evidence)**: CERRADO Y PUBLICADO OFICIALMENTE en `v1.2.0`.
+- **Upgrade C (Cost & Provider Safety Gates)**: CERRADO Y VERIFICADO (`closure.json` status `VERIFIED`).
+  - 20/20 pruebas canónicas P1 de Upgrade C pasando al 100% en 6 suites dedicadas.
+  - Gates `ProviderCapabilityGate` y `BillableActionGate` implementados con fail-closed default deny.
+  - Cost ledger (`cost-ledger.json`) validado, offline verification purity garantizada.
+- **Upgrade D (Context Capsule / Context Compression)**: CERRADO Y VERIFICADO (`closure.json` status `VERIFIED`, capsule `VALID` y `FRESH`).
+  - 20/20 pruebas canónicas de Upgrade D pasando al 100% en 8 suites dedicadas.
+  - Serializador canónico determinista, defensa de secretos fail-closed, presupuesto 32KB/64KB.
+  - Comandos CLI `gemstack context` y etapa 5.2 en `gemstack verify`.
+  - 100/100 pruebas físicas totales pasando en 25 suites sin dependencias externas.
+  - Preparado para release estable `v1.3.0`.
 
 ## 3. Archivos y cambios
-- `src/lib/contracts.js`: Parser column-0 fenced, esquemas de 6 contratos, resolución de herencia y detección de contradicciones.
-- `src/lib/hasher.js`: Hashing canónico SHA-256 (64 hex lowercase) con normalización CRLF->LF y rechazo de BOM UTF-8.
-- `src/lib/findings.js`: Fingerprints canónicos SHA-256 de 64 caracteres, display token de 12 caracteres y excepciones con `contextHash`.
-- `src/lib/state.js`: Persistencia atómica de `state.json` (solo operativo) y sidecar histórico `.gemstack.json`.
-- `src/commands/verify.js`: Paso 4/5 de consistencia arquitectónica y hashes congelados.
-- `tests/`: 5 suites unitarias (`contracts.test.js`, `hasher.test.js`, `findings.test.js`, `init.test.js`, `verify.test.js`).
-- `docs/architecture-consistency.md`: Referencia técnica integral de consistencia y congelamiento de fases.
-- `CHANGELOG.md`, `README.md`, `RELEASE_NOTES.md`, `package.json`: Versión v1.1.0 documentada y preparada para release.
+- `src/lib/test-matrix.js`: Parser de `gemstack-test-matrix`, validación de esquema de 20 tests canónicos y cálculo de `acceptanceSignature` canónico SHA-256.
+- `src/lib/closure-context.js`: Parser de bindings y gates de `plan.md`, metadatos de `tasks.md`, trazabilidad bidireccional, resolución de `RelevantClosureFiles`, `computeContentAggregateHash` y cálculo de `closureContextHash`.
+- `src/lib/runner-adapters.js`: Adaptador nativo seguro de runner `node:test`, parser TAP de resultados, motor de reconciliación aritmética canónica, ejecutor seguro de compuertas `PACKAGE_SCRIPT` y serializador atómico de `closure.json`.
+- `src/commands/collect.js`: Comando mutador dedicado que ejecuta tests y gates para generar `specs/<feature>/closure.json`.
+- `src/commands/ship.js`: Compuerta de transición a `SHIPPED` que exige evidencia de cierre fresca y verificada.
+- `src/commands/verify.js`: Etapa 5/6 agregada de verificación de evidencia mecánica de cierre en modo estrictamente de solo lectura (0 mutaciones en disco).
+- `src/cli.js`: Registro de comandos `collect` y `ship`.
+- `specs/007-mechanical-test-matrix-closure-evidence/`: Artefactos congelados `spec.md`, `plan.md`, `tasks.md` y evidencia de cierre generada `closure.json`.
+- `tests/`: 6 nuevas suites de prueba (`test-matrix.test.js`, `reconciliation.test.js`, `runner-adapter.test.js`, `traceability.test.js`, `closure-manifest.test.js`, `closure-gates.test.js`).
+- `specs/templates/`: Actualizadas plantillas de `spec.md`, `plan.md` y `tasks.md` con bloques canónicos de Upgrade B.
+- `.agents/skills/`: Actualizados skills (`gemstack-spec`, `gemstack-plan`, `gemstack-tasks`, `gemstack-qa`, `gemstack-ship`).
+- `docs/`, `README.md`, `package.json`: Documentación técnica y script de test con enumeración explícita de las 11 suites físicas.
 
 ## 4. Intentos fallidos
 - Se confirmó en proyectos reales que scripts de prueba con sintaxis `2>nul` en `package.json` provocan que PowerShell/Bash enmascaren errores y retornen código de salida 0 con 0 tests ejecutados. Ahora esto es detectado como error por `gemstack verify` y prohibido en la Constitución.
-- **2026-09-11**: En el reporte de Upgrade A, se produjo un drift en la nomenclatura y categorización de la matriz P1 canónica (mencionando A04-A06, D03-D04, E03 y sugiriendo incorrectamente merge de múltiples bloques). Se restauró la correlación canónica estricta de 25 tests P1 aprobados (A=3, B=8, C=4, D=2, E=2, F=2, G=2, H=2) y la regla estricta de parser de 2+ bloques -> CONTRACT_PARSE_ERROR.
+- **2026-09-11**: En el reporte de Upgrade A, se produjo un drift en la nomenclatura y categorización de la matriz P1 canónica. Se restauró la correlación canónica estricta de 25 tests P1 aprobados y la regla estricta de parser de 2+ bloques -> CONTRACT_PARSE_ERROR.
+- **Node 20+ Subprocess Recursion**: Al ejecutar `node --test` como subproceso desde un proceso de test runner, `process.env.NODE_TEST_CONTEXT` suprimía la ejecución de archivos hijos con warning de recursión. Se resolvió sanitizando las variables `NODE_TEST_CONTEXT` y `NODE_TEST_WORKER_ID` en el entorno del proceso hijo.
+- **Windows spawn 'npm.cmd' EINVAL**: Node 22+ en Windows genera `EINVAL` al invocar `spawn('npm.cmd', ..., { shell: false })`. Se resolvió ejecutando directamente el binario `npm-cli.js` vía `process.execPath` cuando se detecta en Windows, respetando la regla constitucional de `shell: false`.
+- **Closure Manifest Self-Reference**: Al incluir `specs/<feature>/closure.json` en los archivos de implementación de `tasks.md`, `closureContextHash` cambiaba cada vez que `closure.json` era escrito, provocando que la evidencia se marcara como `STALE` inmediatamente después de recolectarse. Se resolvió excluyendo explícitamente `closure.json` de la agregación de hashes de contexto de implementación (`implementationContextHash`).
 
 ## 5. Próximos pasos
-1. Validar el nuevo ruteo semántico en sesiones de desarrollo reales.
-2. Considerar `npx gemstack verify` en los hooks o pipelines de CI de proyectos que consumen Gemstack.
+1. Completar la publicación y git tag de la versión minor `v1.3.0`.
+2. Proceder a Upgrade E (SPEC ONLY) una vez autorizada la fase siguiente.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemstack-ai",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Agentic Spec-Driven Development framework for Gemini/Antigravity",
   "main": "src/cli.js",
   "bin": {
@@ -10,7 +10,7 @@
     "node": ">=18.18.0"
   },
   "scripts": {
-    "test": "node --test tests/contracts.test.js tests/hasher.test.js tests/findings.test.js tests/init.test.js tests/verify.test.js",
+    "test": "node --test tests/contracts.test.js tests/hasher.test.js tests/findings.test.js tests/init.test.js tests/verify.test.js tests/test-matrix.test.js tests/reconciliation.test.js tests/runner-adapter.test.js tests/traceability.test.js tests/closure-manifest.test.js tests/closure-gates.test.js tests/cost-ledger.test.js tests/environment-provider-safety.test.js tests/provider-capability-gate.test.js tests/billable-action-gate.test.js tests/provider-fallback.test.js tests/verification-purity-cost.test.js tests/context-determinism.test.js tests/context-authority.test.js tests/context-freshness.test.js tests/context-constraints.test.js tests/context-secrets.test.js tests/context-size-budget.test.js tests/context-purity.test.js tests/context-legacy.test.js",
     "gemstack:verify": "node src/cli.js verify",
     "pack:dry": "npm pack --dry-run",
     "ci:frontmatter": "node scripts/ci/check-frontmatter.js",

package/specs/007-mechanical-test-matrix-closure-evidence/.gemstack.json

@@ -0,0 +1,5 @@
+{
+  "phase_hashes": {},
+  "historical_findings": [],
+  "accepted_exceptions": []
+}

package/specs/007-mechanical-test-matrix-closure-evidence/closure.json

@@ -0,0 +1,59 @@
+{
+  "schema": "gemstack-closure",
+  "version": 1,
+  "feature": "specs/007-mechanical-test-matrix-closure-evidence/",
+  "generated_at": "2026-09-11T16:47:26.609Z",
+  "status": "VERIFIED",
+  "closure_context": {
+    "closure_context_hash": "d0587bf1f8770e142d2d0bb1bd637426f43794100d6514b2f41f9d004c69c8d8",
+    "repository_type": "git",
+    "git_commit": "afb384d2bced7ccf08445d9459a9e3211925658b",
+    "working_tree_clean": false,
+    "relevant_files_digest": "77e03ca88572d0fbbb69df1dd599c9f16e2903db3c4a740f50a0ec4a0459b6ae"
+  },
+  "acceptance_signature": "d6971eadf2e8238c87fa67fb380e2acd80181906a95168c19a57b3a24bf4d9bb",
+  "canonical_summary": {
+    "required_total": 20,
+    "required_passed": 20,
+    "supplemental_total": 0,
+    "supplemental_passed": 0
+  },
+  "physical_summary": {
+    "supporting_total": 0,
+    "supporting_passed": 0,
+    "total_executed": 20,
+    "total_passed": 20,
+    "total_failed": 0,
+    "total_skipped": 0
+  },
+  "reconciliation": {
+    "math_valid": true,
+    "phantoms_detected": 0,
+    "orphans_detected": 0,
+    "missing_canonical_ids": []
+  },
+  "task_traceability_summary": {
+    "tasks_total": 22,
+    "tasks_with_validation": 20,
+    "tasks_documentation_only": 2,
+    "unmapped_canonical_tests": []
+  },
+  "required_gates": {
+    "project-tests": "PASS",
+    "gate-ci-frontmatter": "PASS",
+    "gate-ci-mojibake": "PASS"
+  },
+  "supplemental_gates": {},
+  "exceptions": [],
+  "evidence_sources": [
+    {
+      "type": "PACKAGE_SCRIPT",
+      "script": "test",
+      "runner": "node:test",
+      "exit_code": 0,
+      "duration_ms": 257
+    }
+  ],
+  "blockers": [],
+  "warnings": []
+}