gemstack-ai 1.2.0 → 1.4.0

package/.gemstack/state.json

@@ -1,17 +1,18 @@
 {
   "version": "0.1",
-  "current_phase": "shipped",
+  "current_phase": "closure",
   "status": "SHIPPED",
-  "stop_reason": "UPGRADE_B_SHIPPED_DONE",
-  "active_spec": null,
+  "stop_reason": "UPGRADE_C_SHIPPED_DONE",
+  "active_spec": "specs/010-agent-swarm-visual-qa",
   "completed_phases": [
     "spec",
-    "plan"
+    "plan",
+    "tasks"
   ],
   "phase_hashes": {
-    "spec": "75f7b5aee9a7d45836128f619ba67d0870c9be3a2634d9152b01c6501faa513d",
-    "plan": "c77a3b1410d3b3028b72d66db524c6a23b0998dce12dddaee2507b4e446aec3b",
-    "tasks": "69ea9ae8557a41f98102c7b91905f74b3645ea59cbe301a54425216d5789b1d8"
+    "spec": "767c75151f9c53a70cfa6fcec85d29bccf5e3021004580878fb81ea3c4955ed7",
+    "plan": "d6f960f97bc6bcdb20daddc3c749c5f9f155c1407e0a8b81210cdf350bdad72c",
+    "tasks": "9931dda795d31bf29349ba5f20dc7631cb6a8974b91134ff577c57dd6b9aad7e"
   },
   "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,103 @@
 
 All notable changes to this project will be documented in this file.
 
+## [v1.4.0] - 2026-09-11
+
+### Added
+- **Agent Swarm Planning & Validation (Upgrade E)**: Deterministic multi-worker wave planning and coordination verification framework.
+  - Deterministic swarm planning contracts and canonical `swarm.json` manifest schema.
+  - Task ownership and write-set partitioning: enforces disjoint write boundaries per wave (`write_set(T1) ∩ write_set(T2) = ∅`).
+  - Write-collision detection: automatically detects overlapping write sets and serializes conflicting tasks into sequential waves.
+  - Dependency wave scheduling: preserves task prerequisite graphs and rejects circular dependencies (`SWARM_DEPENDENCY_CYCLE`).
+  - Task-scoped context projections: compiles minimal, role-tailored contexts derived from `context-capsule.json`.
+  - Context freshness validation: verifies live capsule hash against `source_capsule_hash` to reject stale projections (`SWARM_CONTEXT_STALE`).
+  - Separation of duties gate: mechanically enforces `AUTHOR != REVIEWER` (`SWARM_SELF_REVIEW_DETECTED`).
+  - Provider policy and budget gating: integrates with Upgrade C `ProviderCapabilityGate` and `BillableActionGate` to prevent budget runaway.
+  - Subagent limits enforcement: strictly blocks unauthorized recursive worker spawning.
+  - Pure offline read-only verification (Stage 5.3 in `gemstack verify`): validates swarm manifests without worker or agent execution.
+  - Explicit non-execution invariant: Gemstack core does NOT execute autonomous coding agents.
+- **Visual QA Evidence (Upgrade E)**: Mechanical, offline visual verification architecture based on cryptographic digests and neutral masking.
+  - Canonical `visual-qa.json` manifest schema declaring route, deterministic viewport dimensions, and approved baseline references.
+  - Deterministic viewport specifications: standard profiles with explicit width, height, and device scale factor.
+  - Cryptographic baseline pinning: baseline images tracked via canonical SHA-256 byte digests (`image_sha256`).
+  - Tampering detection: flags baseline image mutations on disk (`VQA_BASELINE_TAMPERED`).
+  - Neutral selector masking: masks dynamic elements (`[MASKED_NEUTRAL]`) to prevent flaky subpixel and timestamp diffs.
+  - Mandatory automatic password & credential masking: automatically replaces sensitive input fields (`type=password`, `data-sensitive=true`) with `[MASKED_SECRET]`.
+  - Structured visual evidence comparison: fast SHA-256 digest match path with offline tolerance-bounded diffing (`max_diff_percentage`).
+  - Explicit baseline promotion: baselines are NEVER auto-updated or healed during test or verify; requires explicit `gemstack vqa promote <scenario-id>`.
+  - Pure offline read-only verification (Stage 5.4 in `gemstack verify`): zero browser launches, zero network calls, zero file mutations.
+  - Explicit non-execution invariant: Gemstack core does NOT launch browsers and does NOT capture screenshots automatically.
+- **New CLI Surfaces**:
+  - `gemstack swarm plan [--json]`: compiles `tasks.md` into deterministic concurrent waves.
+  - `gemstack swarm validate [--json]`: validates write partitions, review separation, and context freshness.
+  - `gemstack vqa validate [--json]` (or `gemstack visual validate`): validates visual QA manifests, viewports, baselines, and evidence offline.
+  - `gemstack vqa promote <scenario-id>` (or `gemstack visual promote`): explicitly promotes live evidence to approved canonical baseline.
+
+### Changed
+- `gemstack verify` extended with Stage 5.3 (Swarm Audit) and Stage 5.4 (Visual QA Audit) running in pure read-only mode.
+- `src/lib/closure-context.js` updated to track `swarm.json` and `visual-qa.json` in closure context hashing, and support alphanumeric task IDs (`UE-T001`..`T029`).
+- `package.json` test script updated to register the 5 new Upgrade E test suites.
+
+### Compatibility
+- 100% backward compatible with existing Gemstack repositories and frozen contracts from Upgrades A, B, C, and D.
+- Zero external runtime npm dependencies added (`package.json` dependencies remain `{}`).
+- Zero external development npm dependencies added (`package.json` devDependencies remain `{}`).
+
+### Validation
+- 29/29 Upgrade E tasks COMPLETE.
+- 20/20 Upgrade E canonical acceptance tests passing (`TEST-SWARM-A01`..`E02`, `TEST-VISUAL-A01`..`E02`).
+- 10/10 Upgrade E bootstrap contracts passing.
+- 26/26 adversarial test cases passing.
+- 126/126 physical tests passing across 14 suites with 0 failures and 0 skipped.
+- Full CI test matrix (`npm run ci:all`) passing cleanly.
+- `gemstack verify` exit code 0 with 0 errors and 0 open blockers.
+- Swarm manifest verified: `VALID` and `FRESH`.
+- Visual QA manifest verified: `VALID` and `FRESH`.
+- Closure evidence: `specs/010-agent-swarm-visual-qa/closure.json` status `VERIFIED`.
+
+## [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,17 +108,96 @@ 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.
 
-## 🐝 Advanced Autonomy (The WOW Update)
+## 🛡️ 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.
+- **Core Invariant**: `NO PROOF OF AUTHORIZATION = NO COMMERCIAL EXECUTION`.
+
+## 📦 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.
+- **Core Invariant**: `Context Capsule = derived continuation context NOT project authority`.
+
+## 🐝 Agent Swarm Planning & Validation
+
+Gemstack Upgrade E introduces deterministic multi-worker planning and write-set partition validation:
+- **`gemstack swarm plan`**: Compiles parallelizable `tasks.md` items into deterministic concurrent waves in `specs/<feature>/swarm.json`.
+- **Exclusive Write Boundaries**: Validates that concurrent tasks possess strictly disjoint write sets (`write_set(T1) ∩ write_set(T2) = ∅`), mathematically preventing write collisions.
+- **Collision Avoidance**: Overlapping write sets are automatically serialized into sequential waves (`SWARM_WRITE_COLLISION_PREVENTED`).
+- **Separation of Duties Gate**: Non-waivable mechanical check enforcing `author != reviewer` on all task reviews (`SWARM_SELF_REVIEW_DETECTED`).
+- **Task-Scoped Context Projections**: Projects minimal, structured context payloads derived from `context-capsule.json` without raw chat transcripts or prompt noise.
+- **Provider & Budget Integration**: Intercepts model invocations via Upgrade C `ProviderCapabilityGate` and `BillableActionGate` to prevent budget breaches.
+- **`gemstack swarm validate`**: Pure read-only validation of wave partitions, task ownership, and review independence.
+- **Explicit Boundary**: *Gemstack core coordinates and validates; Gemstack core does NOT execute autonomous coding agents.*
+
+## 👁️ Visual QA Evidence & Offline Verification
+
+Gemstack Upgrade E provides mechanical visual verification grounded in cryptographic digests and offline comparisons:
+- **Canonical Visual Manifest (`visual-qa.json`)**: Declares scenario routes, deterministic viewports, selector masks, baseline digests, and diff tolerances.
+- **Deterministic Viewports**: Standardized profiles (Desktop, Mobile, Tablet) with locked width, height, and device scale factor.
+- **Cryptographic Baseline Hashing**: Baselines are tracked and pinned via canonical SHA-256 hashes (`image_sha256`); flags disk tampering (`VQA_BASELINE_TAMPERED`).
+- **Neutral & Secret Masking**: Eliminates dynamic timestamp/counter diff flakiness (`[MASKED_NEUTRAL]`) and enforces mandatory automatic masking on password and credential fields (`[MASKED_SECRET]`).
+- **Structured Evidence Comparison**: Fast SHA-256 match path with offline tolerance-bounded diffing (`max_diff_percentage`).
+- **Explicit Promotion Semantics**: Baselines are NEVER auto-updated or healed during test or verify; requires explicit `gemstack vqa promote <scenario-id>`.
+- **`gemstack vqa validate`**: Pure read-only offline validation of manifests, baselines, and evidence completeness.
+- **Explicit Boundary**: *Gemstack core inspects and diffs evidence; Gemstack core does NOT launch browsers and does NOT capture screenshots automatically. Capture remains external/adapted.*
+
+## 🏛️ Architectural Principles
+
+Gemstack operates on strict, non-negotiable architectural principles:
+
+```text
+authority > derived artifacts
+evidence ≠ authority
+verify = validate
+agent output ≠ architecture
+visual evidence ≠ architecture
+credentials ≠ authorization
+provider availability ≠ permission
+unknown cost ≠ free
+fallback ≠ inherited authorization
+agent says done ≠ task mechanically complete
+author ≠ reviewer where independent review is required
+```
 
-Gemstack isn't just passive documents; it actively orchestrates agentic capabilities:
+## 💻 CLI Reference
 
-| Command | Action |
-|---------|--------|
-| `/swarm` | Orchestrates parallel subagents for tasks marked `[P]` |
-| `/qa-visual` | Spawns sandbox browsers to visually assert Acceptance Criteria |
-| `/dashboard` | Generates a rich, interactive inline UI of your project's progress |
-| `/heal` | Hooks into GitHub CLI (`gh`) to read failing CI logs and auto-push fixes |
-| `/sandbox` | Wraps risky AI execution inside an ephemeral Docker container |
+Gemstack provides a focused, deterministic CLI surface:
+
+```bash
+# Core verification & collection
+gemstack verify [--json] [--target <dir>]     # 6-stage read-only audit (0 mutations, 0 network)
+gemstack collect [--target <dir>]             # Executes test runner & records closure.json
+gemstack ship [--target <dir>]                # Transitions lifecycle to SHIPPED if closure is VERIFIED
+
+# Context capsule (Upgrade D)
+gemstack context generate [--force]           # Compiles deterministic context-capsule.json
+gemstack context show [--raw]                 # Displays continuation context summary or JSON
+gemstack context verify                       # Verifies capsule freshness and provenance
+
+# Agent swarm (Upgrade E)
+gemstack swarm plan [--json]                  # Compiles tasks into disjoint concurrent waves
+gemstack swarm validate [--json]              # Validates write sets and review attestations
+
+# Visual QA (Upgrade E)
+gemstack vqa validate [--json]                # Validates visual manifest, viewports, and baselines
+gemstack vqa promote <scenario-id>            # Explicitly promotes live evidence to baseline
+```
 
 ## 🪝 Active Security (Git Hooks)
 
@@ -134,6 +213,7 @@ You can install agent skills created by the community directly into your project
 npx gemstack-ai install https://raw.githubusercontent.com/community/gemstack-skills/main/django-expert/SKILL.md
 ```
 
+
 ## 🤖 MCP Server (Model Context Protocol)
 
 Gemstack ships with a built-in MCP server that exposes the SDD state of your project to any MCP-compliant AI client (like Claude Desktop or Cursor). 

package/RELEASE_NOTES.md

@@ -1,5 +1,82 @@
 # Gemstack Release Notes
 
+# Gemstack v1.4.0 — Agent Swarm & Visual QA
+
+## Highlights
+
+### Upgrade E — Agent Swarm Planning & Validation
+- **Deterministic Multi-Worker Planning**: Compiles parallelizable `tasks.md` items into deterministic, phased execution waves recorded in canonical `swarm.json`.
+- **Task Ownership & Exclusive Write Boundaries**: Validates that concurrent tasks possess strictly disjoint file write partitions (`write_set(T1) ∩ write_set(T2) = ∅`), completely preventing parallel write collisions.
+- **Automatic Collision Avoidance**: Automatically serializes conflicting tasks into sequential waves during planning (`SWARM_WRITE_COLLISION_PREVENTED`).
+- **Separation of Duties Gate**: Non-waivable mechanical check enforcing `author != reviewer` on all task reviews (`SWARM_SELF_REVIEW_DETECTED`).
+- **Task-Scoped Context Projections**: Projects minimal, structured context payloads derived from Upgrade D `context-capsule.json` with conversational narrative and raw chat transcripts strictly excluded.
+- **Cryptographic Provenance & Freshness**: Pinned `source_capsule_hash` ensures workers operate against verified project state; flags drift fail-closed (`SWARM_CONTEXT_STALE`).
+- **Provider & Budget Gating**: Intercepts model invocations via Upgrade C `ProviderCapabilityGate` and `BillableActionGate` to prevent runaway spending across concurrent workers.
+- **Worker Limits**: Prevents recursive child agent spawning (`SWARM_RECURSIVE_SPAWN_DENIED`).
+- **Explicit Invariant**: Gemstack core coordinates and validates; it does NOT execute autonomous coding agents.
+
+### Upgrade E — Visual QA Evidence & Offline Verification
+- **Canonical Visual QA Manifest (`visual-qa.json`)**: Declares explicit routes, deterministic viewports, selector masks, baseline references, and diff tolerances.
+- **Deterministic Viewport Specifications**: Locks standardized viewport profiles (Desktop, Mobile, Tablet) with explicit width, height, and device scale factor.
+- **Cryptographic Baseline Hashing**: Baselines are tracked and verified via canonical SHA-256 byte digests (`image_sha256`); flags disk tampering (`VQA_BASELINE_TAMPERED`).
+- **Neutral & Secret Selector Masking**: Neutral masks (`[MASKED_NEUTRAL]`) eliminate font/timestamp flakiness; mandatory automatic masking replaces sensitive input fields (`type=password`) with `[MASKED_SECRET]`.
+- **Structured Evidence Comparison**: Fast SHA-256 digest comparison with offline tolerance-bounded diffing (`max_diff_percentage`).
+- **Explicit Baseline Promotion**: Baselines are NEVER mutated during verification; updates require explicit `gemstack vqa promote <scenario-id>`.
+- **Pure Offline Verification (Stages 5.3 & 5.4)**: `gemstack verify` runs 100% offline with zero browser launches, zero network calls, and zero file mutations.
+- **Explicit Invariant**: Gemstack core inspects evidence; it does NOT launch browsers or capture screenshots.
+
+## Acceptance & Regression Baseline
+- 25 Upgrade A canonical acceptance tests passing.
+- 20 Upgrade B canonical acceptance tests passing.
+- 20 Upgrade C canonical acceptance tests passing.
+- 20 Upgrade D canonical acceptance tests passing.
+- 20 Upgrade E canonical acceptance tests passing (`TEST-SWARM-A01`..`E02`, `TEST-VISUAL-A01`..`E02`).
+- 10 Upgrade E bootstrap contracts passing.
+- 26 Upgrade E adversarial cases passing.
+- 105 total canonical acceptance tests passing.
+- 126 total physical tests passing across 14 explicitly enumerated suites with 0 failures and 0 skipped.
+- Full CI suite (`npm run ci:all`) passing cleanly.
+- Upgrade E closed with closure status `VERIFIED`.
+
+---
+
+# 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.4.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 tests/swarm-partitioning.test.js tests/swarm-review.test.js tests/visual-manifest.test.js tests/visual-diff.test.js tests/swarm-visual-purity.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": []
+}