gemstack-ai 1.3.0 → 1.4.0

package/.gemstack/state.json

@@ -1,18 +1,18 @@
 {
   "version": "0.1",
-  "current_phase": "shipped",
+  "current_phase": "closure",
   "status": "SHIPPED",
   "stop_reason": "UPGRADE_C_SHIPPED_DONE",
-  "active_spec": null,
+  "active_spec": "specs/010-agent-swarm-visual-qa",
   "completed_phases": [
     "spec",
     "plan",
     "tasks"
   ],
   "phase_hashes": {
-    "spec": "9241b9e992f687e80ecef388c79731ece7af9aa75ba989dc8f0b1e9b855f7914",
-    "plan": "6a2e29e9aeda266a71ab435fa09bca3b18521835a69f6020cd8d9f135643e3aa",
-    "tasks": "1697c32a1f6596f317491df68cd1b161e5c77fbbddc74ce3f1e6e00a42619249"
+    "spec": "767c75151f9c53a70cfa6fcec85d29bccf5e3021004580878fb81ea3c4955ed7",
+    "plan": "d6f960f97bc6bcdb20daddc3c749c5f9f155c1407e0a8b81210cdf350bdad72c",
+    "tasks": "9931dda795d31bf29349ba5f20dc7631cb6a8974b91134ff577c57dd6b9aad7e"
   },
   "consistency": {
     "status": "PASS",
@@ -25,4 +25,4 @@
   },
   "last_update": "2026-09-11T17:38:04.916Z",
   "last_completed_feature": "specs/008-cost-provider-safety-gates"
-}
+}

package/CHANGELOG.md

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

package/README.md

@@ -118,6 +118,7 @@ Gemstack Upgrade C guarantees fail-closed safety for commercial, remote, and AI
 - **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
 
@@ -130,18 +131,73 @@ Gemstack Upgrade D enables deterministic, constraint-lossless context compressio
 - **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
+```
 
-## 🐝 Advanced Autonomy (The WOW Update)
+## 💻 CLI Reference
 
-Gemstack isn't just passive documents; it actively orchestrates agentic capabilities:
+Gemstack provides a focused, deterministic CLI surface:
 
-| 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 |
+```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)
 
@@ -157,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,45 @@
 # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gemstack-ai",
-  "version": "1.3.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 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",
+    "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/009-context-capsule/context-capsule.json

@@ -316,7 +316,7 @@
       "value": true
     }
   ],
-  "generated_at": "2026-09-11T18:39:24.919Z",
+  "generated_at": "2026-09-11T19:51:55.434Z",
   "generator": {
     "name": "gemstack",
     "version": "1.2.0"
@@ -352,16 +352,16 @@
   ],
   "project": {
     "active_feature": "specs/009-context-capsule",
-    "current_phase": "shipped",
+    "current_phase": "closure",
     "lifecycle_status": "SHIPPED",
     "name": "gemstack-ai",
     "next_permitted_phase": "PLAN"
   },
   "provenance": {
-    "source_set_hash": "c4f41904cf21ad6f8621e310650de48b7012c40a4a73010a62b37ea633d576b5",
+    "source_set_hash": "cb553121ecd975b8c39e1378e0ff07c9adb2d12ef323f2088c34c6780ca33077",
     "sources": [
       {
-        "hash": "a38e279e94ee6bcfb8bae4e9bf407277cdc1c16491539ae6a66bc179befb0ab6",
+        "hash": "e7b3f8427fd31ef9d591b6752716ebbf1831d669c5000297a8816eeeaf5e6936",
         "path": ".gemstack/state.json",
         "role": "LIFECYCLE_STATE"
       },

package/specs/010-agent-swarm-visual-qa/.gemstack.json

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

package/specs/010-agent-swarm-visual-qa/closure.json

@@ -0,0 +1,59 @@
+{
+  "schema": "gemstack-closure",
+  "version": 1,
+  "feature": "specs/010-agent-swarm-visual-qa",
+  "generated_at": "2026-09-11T19:52:14.736Z",
+  "status": "VERIFIED",
+  "closure_context": {
+    "closure_context_hash": "8be65c934d6f21da5ea49237613ef80705121c7006061a55f6db2fa24216ef41",
+    "repository_type": "git",
+    "git_commit": "832550278fa95d3ed571c8ec2f7db9830ddd9ebc",
+    "working_tree_clean": false,
+    "relevant_files_digest": "d02611dc5c123f386294bb6807b2c424fbc1c4666586a3284686cfd99452a905"
+  },
+  "acceptance_signature": "4c62312b07e949480087e1bced495abfe44f137bf5a04ac5d87c8ef4ccd3fbeb",
+  "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": 29,
+    "tasks_with_validation": 29,
+    "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": 351
+    }
+  ],
+  "blockers": [],
+  "warnings": []
+}