gemstack-ai 1.2.0 → 1.3.0

package/.gemstack/state.json

@@ -2,16 +2,17 @@
   "version": "0.1",
   "current_phase": "shipped",
   "status": "SHIPPED",
-  "stop_reason": "UPGRADE_B_SHIPPED_DONE",
+  "stop_reason": "UPGRADE_C_SHIPPED_DONE",
   "active_spec": null,
   "completed_phases": [
     "spec",
-    "plan"
+    "plan",
+    "tasks"
   ],
   "phase_hashes": {
-    "spec": "75f7b5aee9a7d45836128f619ba67d0870c9be3a2634d9152b01c6501faa513d",
-    "plan": "c77a3b1410d3b3028b72d66db524c6a23b0998dce12dddaee2507b4e446aec3b",
-    "tasks": "69ea9ae8557a41f98102c7b91905f74b3645ea59cbe301a54425216d5789b1d8"
+    "spec": "9241b9e992f687e80ecef388c79731ece7af9aa75ba989dc8f0b1e9b855f7914",
+    "plan": "6a2e29e9aeda266a71ab435fa09bca3b18521835a69f6020cd8d9f135643e3aa",
+    "tasks": "1697c32a1f6596f317491df68cd1b161e5c77fbbddc74ce3f1e6e00a42619249"
   },
   "consistency": {
     "status": "PASS",
@@ -22,6 +23,6 @@
     "freeze": false,
     "allowed_paths": []
   },
-  "last_update": "2026-09-11T16:49:53.470Z",
-  "last_completed_feature": "specs/007-mechanical-test-matrix-closure-evidence/"
+  "last_update": "2026-09-11T17:38:04.916Z",
+  "last_completed_feature": "specs/008-cost-provider-safety-gates"
 }

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 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.

package/README.md

@@ -108,6 +108,29 @@ Gemstack Upgrade B guarantees that what was planned is what was physically teste
 - **`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,42 @@
 # 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

package/handoff.md

@@ -8,16 +8,18 @@ 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 PUBLICADO OFICIALMENTE como `gemstack-ai@1.1.2` en npm y GitHub Release.
-- **Upgrade B (Mechanical Test Matrix & Closure Evidence)**: CERRADO Y PREPARADO PARA RELEASE como `gemstack-ai@1.2.0`.
-  - 20/20 pruebas canónicas P1 de Upgrade B pasando al 100% en 6 nuevas suites.
-  - 25/25 pruebas canónicas P1 de Upgrade A preservadas con 0 regresiones.
-  - 53/53 pruebas físicas totales ejecutadas y pasando con 0 errores en CI/CD local (`npm test`, `npm run ci:all`).
-  - Comando mutador `gemstack collect` implementado y probado en Feature 007, generando `closure.json` atómicamente.
-  - Comando `gemstack verify` ampliado a 6 etapas estrictamente read-only con validación de frescura contra `closureContextHash`.
-  - Compuerta de cierre `gemstack ship` ejecutada exitosamente con estado `VERIFIED` y transición de ciclo de vida formal.
-  - Zero dependencias externas añadidas en producción.
-  - Excluidos completamente Upgrade C y Upgrade D.
+- **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/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.
@@ -41,5 +43,5 @@ Evolucionar Gemstack incorporando el feedback de producción real de proyectos a
 - **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. Completar la publicación de la versión minor v1.2.0 en GitHub Release y npm.
-2. Iniciar la fase de arquitectura de Upgrade C (Cost & Provider Safety Gates) en su ciclo correspondiente.
+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.2.0",
+  "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 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",
+    "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/008-cost-provider-safety-gates/.gemstack.json

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

package/specs/008-cost-provider-safety-gates/closure.json

@@ -0,0 +1,59 @@
+{
+  "schema": "gemstack-closure",
+  "version": 1,
+  "feature": "specs/008-cost-provider-safety-gates",
+  "generated_at": "2026-09-11T17:33:08.020Z",
+  "status": "VERIFIED",
+  "closure_context": {
+    "closure_context_hash": "551b1853a7bbac24decba595284104f24dc34f5feed858808e3f59bdfa36c7ff",
+    "repository_type": "git",
+    "git_commit": "1e19c3d7cc527099e6e7c74cbfdbd4cdf4c23584",
+    "working_tree_clean": false,
+    "relevant_files_digest": "5886c19984cde85fae8b2acdedc4a890b9f7d0e46df3622bc738de482325c625"
+  },
+  "acceptance_signature": "456b3799bb96ce72a8b82d9739bcf469b9fa1e9eb170a2726ea2308bcbb4cf9c",
+  "canonical_summary": {
+    "required_total": 20,
+    "required_passed": 20,
+    "supplemental_total": 0,
+    "supplemental_passed": 0
+  },
+  "physical_summary": {
+    "supporting_total": 6,
+    "supporting_passed": 6,
+    "total_executed": 26,
+    "total_passed": 26,
+    "total_failed": 0,
+    "total_skipped": 0
+  },
+  "reconciliation": {
+    "math_valid": true,
+    "phantoms_detected": 0,
+    "orphans_detected": 0,
+    "missing_canonical_ids": []
+  },
+  "task_traceability_summary": {
+    "tasks_total": 20,
+    "tasks_with_validation": 20,
+    "tasks_documentation_only": 0,
+    "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": 790
+    }
+  ],
+  "blockers": [],
+  "warnings": []
+}