gemstack-ai 1.1.2 → 1.2.0

package/specs/007-mechanical-test-matrix-closure-evidence/spec.md

@@ -0,0 +1,597 @@
+# Especificación de Funcionalidad: Mechanical Test Matrix & Closure Evidence (Upgrade B)
+
+**Feature Branch**: `007-mechanical-test-matrix-closure-evidence`  
+**Feature Directory**: `specs/007-mechanical-test-matrix-closure-evidence/`  
+**Lifecycle Status**: `SPEC_COMPLETE`  
+**Stop Reason**: `SPEC_COMPLETE_AWAITING_REVIEW`
+
+---
+
+## 1. Primary Objective & Problem Statement
+
+Gemstack v1.1.2 operates as a deterministic architecture consistency engine (`FrozenContractRegistry`, cross-phase inheritance, mutation detection, finding fingerprints, sidecar persistence). However, architectural consistency alone does not guarantee mechanical closure truth:
+1. An AI agent can report "25/25 tests passing" when only 11 or 0 tests were actually executed.
+2. AI agents frequently fabricate phantom tests, execute tautological assertions, count tests without asserting their status, or report total counts that diverge mathematically from physical test runner outputs.
+3. Test suite boundaries blur between canonical acceptance requirements (P1), edge-case internal tests, and supporting/sanity tests.
+4. Premature closure (`SHIPPED`) is claimed without verifiable, mechanical evidence linking tasks, physical tests, execution runs, and fresh repository state.
+
+**Upgrade B** promotes Gemstack from an *Architecture Consistency Engine* to an **Architecture Consistency and Mechanical Implementation Closure Engine**. It eliminates false closure by establishing a deterministic, verifiable chain of custody:
+```text
+CANONICAL TEST DECLARATION (spec.md)
+  → TEST RUNNER & SUITE MAPPING (plan.md)
+    → TASK EXECUTION & TEST BINDING (tasks.md)
+      → NATIVE RUNNER EXECUTION (node:test / npm test)
+        → STRUCTURED CLOSURE MANIFEST (closure.json)
+          → MECHANICAL CLOSURE GATE (gemstack verify / gemstack ship)
+```
+
+---
+
+## 2. Invariants & Bootstrap Contracts
+
+This feature dogfoods Gemstack contracts and establishes bootstrap architecture invariants:
+
+```gemstack-contracts
+[
+  {
+    "id": "zero-dependency-core",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Upgrade B implementation must introduce zero external production npm dependencies, using Node.js built-ins exclusively."
+  },
+  {
+    "id": "upgrade-b-taxonomy-types",
+    "type": "ENUM_SET",
+    "values": [
+      "CANONICAL_TEST",
+      "PHYSICAL_TEST",
+      "SUPPORTING_TEST",
+      "DECLARED_TEST",
+      "EXECUTED_TEST",
+      "PASSED_TEST",
+      "FAILED_TEST",
+      "SKIPPED_TEST",
+      "PHANTOM_TEST",
+      "ORPHAN_TEST"
+    ],
+    "description": "Canonical test taxonomy and state classifications in Upgrade B."
+  },
+  {
+    "id": "upgrade-b-closure-gate-levels",
+    "type": "ENUM_SET",
+    "values": [
+      "REQUIRED",
+      "SUPPLEMENTAL"
+    ],
+    "description": "Strictness levels for mechanical closure gates."
+  },
+  {
+    "id": "upgrade-b-closure-status-values",
+    "type": "ENUM_SET",
+    "values": [
+      "NOT_EVALUATED",
+      "BLOCKED",
+      "VERIFIED",
+      "VERIFIED_WITH_EXCEPTIONS",
+      "STALE"
+    ],
+    "description": "Formal mechanical closure states."
+  },
+  {
+    "id": "mechanical-reconciliation-exact",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Total physical executed tests must exactly equal canonical executed tests plus supporting executed tests."
+  },
+  {
+    "id": "closure-manifest-is-derived-only",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "closure.json is a derived mechanical evidence snapshot generated by collection, never hand-edited."
+  },
+  {
+    "id": "verify-is-read-only",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "gemstack verify is strictly read-only: it validates evidence and never collects, mutates, or regenerates closure.json."
+  },
+  {
+    "id": "git-is-optional-for-closure",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Git metadata is optional enrichment; closure context resolution does not require git repository existence."
+  },
+  {
+    "id": "no-generic-test-runner",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Gemstack does not reimplement a test runner; it interfaces with native runners via standardized adapters."
+  },
+  {
+    "id": "legacy-specs-preserve-compatibility",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Specs without gemstack-test-matrix blocks operate in progressive legacy mode without blocking or breaking backward compatibility."
+  }
+]
+```
+
+---
+
+## 3. Canonical Test Taxonomy & Terminology
+
+Upgrade B establishes precise, unambiguous definitions for test inventory and execution:
+
+| Term | Definition |
+| :--- | :--- |
+| **`CANONICAL_TEST`** | A formal acceptance test specification defined in `spec.md` with a unique ID (`TEST-CLOSURE-xxx`), layer, category, description, and pass criteria. It represents a non-negotiable contract requirement. |
+| **`PHYSICAL_TEST`** | An actual executable test function in code (e.g. `it(...)`, `test(...)`) identifiable by runner, file path, line number, or canonical annotation. |
+| **`SUPPORTING_TEST`** | A valid physical test in the codebase (e.g., edge case, benchmark, regression helper) that executes during test runs but is not designated as a primary canonical acceptance test. |
+| **`DECLARED_TEST`** | A test ID explicitly listed in specification or plan tables as intended for implementation. |
+| **`EXECUTED_TEST`** | A physical test that was actually invoked and executed by the native test runner during the recorded verification run. |
+| **`PASSED_TEST`** | An executed test that completed with zero assertion failures and zero uncaught exceptions. |
+| **`FAILED_TEST`** | An executed test that threw an assertion error, unhandled rejection, or runner failure. |
+| **`SKIPPED_TEST`** | A test ignored or skipped by runner directives (e.g. `test.skip`). Skipped canonical tests are treated as unfulfilled requirements. |
+| **`PHANTOM_TEST`** | An ID claimed in structured closure evidence as executed or passed, but absent from authoritative runner execution logs. Strictly non-waivable. |
+| **`ORPHAN_TEST`** | A physical test attempting to fulfill a canonical test ID that does not exist in the frozen specification test matrix. |
+
+---
+
+## 4. Structured Test Matrix Format (`gemstack-test-matrix`)
+
+Canonical tests are declared inside `spec.md` using column-0 fenced blocks with tag `gemstack-test-matrix`, formatted as strict JSON:
+
+```gemstack-test-matrix
+[
+  {
+    "id": "TEST-CLOSURE-A01",
+    "category": "PARSING",
+    "layer": "UNIT",
+    "description": "Parses a valid gemstack-test-matrix block from spec.md into structured CanonicalTest objects.",
+    "pass_criteria": "Returns array of CanonicalTest objects matching all schema fields.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-A02",
+    "category": "PARSING",
+    "layer": "UNIT",
+    "description": "Emits TEST_MATRIX_PARSE_ERROR on malformed JSON or TEST_MATRIX_DUPLICATE_ID on duplicate IDs.",
+    "pass_criteria": "Throws or reports specific Upgrade B error code without using Upgrade A contract error codes.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-A03",
+    "category": "PARSING",
+    "layer": "UNIT",
+    "description": "Ignores non-column-0 or un-tagged fenced blocks cleanly.",
+    "pass_criteria": "Returns empty matrix or only parses strict column-0 blocks without throwing.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-B01",
+    "category": "SIGNATURE",
+    "layer": "UNIT",
+    "description": "Computes deterministic SHA-256 acceptanceSignature digest over canonical test matrix.",
+    "pass_criteria": "Produces identical 64-char lowercase hex digest regardless of key order in input JSON objects.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-B02",
+    "category": "SIGNATURE",
+    "layer": "UNIT",
+    "description": "Emits ACCEPTANCE_SIGNATURE_MISMATCH when structured matrix disagrees with expected signature on approved artifact.",
+    "pass_criteria": "Raises ACCEPTANCE_SIGNATURE_MISMATCH finding distinct from FROZEN_ARTIFACT_CHANGED.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-C01",
+    "category": "RECONCILIATION",
+    "layer": "UNIT",
+    "description": "Verifies exact arithmetic: executed canonical + executed supporting = total physical executed.",
+    "pass_criteria": "Returns pass: true when counts match exactly; returns CLOSURE_RECONCILIATION_FAILURE when counts differ.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-C02",
+    "category": "RECONCILIATION",
+    "layer": "UNIT",
+    "description": "Identifies missing or unexecuted canonical tests when required canonical test IDs are not executed.",
+    "pass_criteria": "Emits REQUIRED_TEST_NOT_EXECUTED or REQUIRED_TEST_MISSING and sets status BLOCKED.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-C03",
+    "category": "RECONCILIATION",
+    "layer": "UNIT",
+    "description": "Detects phantom tests (claimed tests absent from runner execution traces).",
+    "pass_criteria": "Emits non-waivable PHANTOM_TEST finding and halts verification.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-C04",
+    "category": "RECONCILIATION",
+    "layer": "UNIT",
+    "description": "Detects orphan tests (physical tests claiming non-existent canonical IDs).",
+    "pass_criteria": "Emits ORPHAN_TEST finding identifying the unregistered canonical ID.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-D01",
+    "category": "RUNNER_ADAPTER",
+    "layer": "INTEGRATION",
+    "description": "Executes node:test via child_process without shell:true and extracts structured results.",
+    "pass_criteria": "Successfully parses passed, failed, and skipped test counts from execution output.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-D02",
+    "category": "RUNNER_ADAPTER",
+    "layer": "INTEGRATION",
+    "description": "Extracts canonical test IDs embedded in test title strings or metadata.",
+    "pass_criteria": "Correctly associates test outcome with canonical ID TEST-CLOSURE-xxx.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-D03",
+    "category": "RUNNER_ADAPTER",
+    "layer": "UNIT",
+    "description": "Handles runner execution failure or non-zero exit code gracefully.",
+    "pass_criteria": "Reports runner failure without crashing Gemstack CLI process.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-E01",
+    "category": "TRACEABILITY",
+    "layer": "UNIT",
+    "description": "Validates unidirectional task binding (TASK -> TEST IDs) and enforces validation_required field.",
+    "pass_criteria": "Raises TASK_VALIDATION_MISSING if validation_required: true lacks valid test bindings.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-E02",
+    "category": "TRACEABILITY",
+    "layer": "UNIT",
+    "description": "Confirms every required canonical test is bound to at least one implementation task.",
+    "pass_criteria": "Raises UNMAPPED_CANONICAL_TEST finding if a canonical test has no associated task.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-F01",
+    "category": "MANIFEST",
+    "layer": "UNIT",
+    "description": "Generates valid closure.json matching schema with complete execution and context metadata.",
+    "pass_criteria": "Serialized JSON matches closure manifest specification with nullable Git fields for non-Git setups.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-F02",
+    "category": "MANIFEST",
+    "layer": "UNIT",
+    "description": "Computes deterministic structured closureContextHash across clean Git, dirty Git, and non-Git setups.",
+    "pass_criteria": "Produces stable SHA-256 digest from canonical JSON object containing repository, phase, signature, and test files context.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-F03",
+    "category": "MANIFEST",
+    "layer": "UNIT",
+    "description": "Verifies read-only detection of stale evidence when relevant bound files change after manifest generation.",
+    "pass_criteria": "gemstack verify marks status STALE and emits CLOSURE_EVIDENCE_STALE without modifying closure.json.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-G01",
+    "category": "GATES",
+    "layer": "INTEGRATION",
+    "description": "Blocks transition to SHIPPED when any REQUIRED closure gate fails or evidence is STALE.",
+    "pass_criteria": "Ship command halts with blocker error and does not mutate lifecycle to SHIPPED.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-G02",
+    "category": "GATES",
+    "layer": "INTEGRATION",
+    "description": "Allows transition to SHIPPED when all REQUIRED gates pass (status VERIFIED or policy-permitted VERIFIED_WITH_EXCEPTIONS).",
+    "pass_criteria": "Ship command proceeds successfully when verified evidence is fresh and valid.",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-CLOSURE-H01",
+    "category": "LEGACY",
+    "layer": "UNIT",
+    "description": "Preserves backward compatibility for specs without gemstack-test-matrix blocks.",
+    "pass_criteria": "Verification passes in legacy mode with informational notice and zero errors.",
+    "gate": "REQUIRED"
+  }
+]
+```
+
+### Schema Attributes for Test Matrix Entries
+- `id` (*string*, required): Unique canonical identifier matching regex `^TEST-[A-Z0-9]+-[A-Z0-9]+$`.
+- `category` (*string*, required): Functional group matching specification sections.
+- `layer` (*enum*, required): `"UNIT"` | `"INTEGRATION"` | `"E2E"` | `"CLI"`.
+- `description` (*string*, required): Human-readable scope and intent of the test.
+- `pass_criteria` (*string*, required): Explicit, deterministic conditions under which the test passes.
+- `gate` (*enum*, required): `"REQUIRED"` (blocks shipping) | `"SUPPLEMENTAL"` (advisory/informational).
+
+### Test Matrix Error Taxonomy (Upgrade B)
+Upgrade B does not reuse Upgrade A `CONTRACT_PARSE_ERROR`. It defines a dedicated parsing error family:
+- `TEST_MATRIX_PARSE_ERROR`: Malformed JSON or malformed column-0 fenced block.
+- `TEST_MATRIX_DUPLICATE_ID`: Duplicate canonical test ID declared within the matrix.
+- `TEST_MATRIX_INVALID_SHAPE`: Missing required attributes, invalid enum values, or regex mismatch.
+
+### Cryptographic Content Digest (`acceptanceSignature`)
+To prevent unauthorized additions, deletions, or modifications to canonical test requirements across phases:
+$$\text{acceptanceSignature} = \text{SHA-256}(\text{normalized_canonical_test_matrix_json})$$
+The `acceptanceSignature` is a deterministic SHA-256 content digest (not an asymmetric digital signature) calculated over the LF-normalized, key-sorted canonical array and is locked into phase hashes and `.gemstack/state.json` when `spec.md` is frozen.
+
+---
+
+## 5. Matrix Distribution Across Phases (Traceability & Separation of Concerns)
+
+| Phase Artifact | Role & Responsibility | Matrix Element |
+| :--- | :--- | :--- |
+| **`spec.md`** | **Declares** what must be accepted. Owns canonical test IDs, criteria, categories, gates, and the `acceptanceSignature`. | Canonical Test Matrix (`gemstack-test-matrix`) |
+| **`plan.md`** | **Maps** canonical tests to technical implementation strategies, runner engines, physical file targets, and directory structures. | Test Execution Plan & Suite Mappings |
+| **`tasks.md`** | **Binds** specific actionable implementation tasks to canonical test IDs (`validation_required: true`). | Task ↔ Test Traceability Mapping |
+| **`src/` & `tests/`** | **Implements** physical test code asserting the criteria. | Physical tests annotated or mapped to test IDs |
+| **`closure.json`** | **Records** mechanical proof of execution, reconciliation, and pass/fail counts. | Generated Closure Manifest |
+
+### Task Binding Direction & `validation_required` Semantics
+- The canonical binding is strictly unidirectional: `TASK → TEST IDs`.
+- Reverse mapping (`TEST → TASKS`) is derived mechanically by the verification engine and must never be stored manually.
+- Every implementation task must declare `validation_required: true | false`.
+- If `validation_required: true` and no valid canonical or supporting test binding is present, `gemstack verify` emits `TASK_VALIDATION_MISSING` as a blocker.
+- Non-functional tasks (e.g. documentation, scaffolding) may declare `validation_required: false`.
+
+---
+
+## 6. Mechanical Reconciliation & Set Semantics
+
+Gemstack strictly enforces exact arithmetic reconciliation and set equality:
+
+$$\text{Total Physical Tests Executed} = \text{Canonical Tests Executed} + \text{Supporting Tests Executed}$$
+
+### Set Semantics for Closure:
+1. **Exact Set Equality**:
+   $$\text{EXPECTED\_REQUIRED\_CANONICAL\_IDS} == \text{EXECUTED\_REQUIRED\_CANONICAL\_IDS}$$
+   - A required canonical test ID that exists in code but was not executed is `REQUIRED_TEST_NOT_EXECUTED`.
+   - A required canonical test ID with no physical test implementation is `REQUIRED_TEST_MISSING`.
+2. **Zero Failures**:
+   $$\text{Failed Tests} = 0 \quad \land \quad \text{Skipped Required Tests} = 0$$
+3. **No Phantoms** (`NO_PHANTOM_TESTS`):
+   Every reported canonical test must map 1:1 to an actual physical test with a verified execution event in native runner output.
+4. **No Orphans** (`NO_ORPHAN_CANONICAL_BINDINGS`):
+   Every physical test claiming a canonical test ID must reference an ID present in the frozen `gemstack-test-matrix`. Physical tests without canonical IDs are classified as `SUPPORTING_TEST`.
+
+If any equation or set condition is violated, `gemstack verify` immediately emits `CLOSURE_RECONCILIATION_FAILURE` or specific taxonomy findings.
+
+Additionally:
+1. **Set Inclusion**:
+   $$\text{Declared Required Canonical IDs} \subseteq \text{Executed Passed Canonical IDs}$$
+2. **Zero Failures**:
+   $$\text{Failed Tests} = 0 \quad \land \quad \text{Skipped Required Tests} = 0$$
+3. **No Phantoms**:
+   Every reported canonical test must map 1:1 to an actual physical test with a verified execution event in the runner output.
+4. **No Orphans**:
+   Every physical test referencing a canonical test ID must reference an ID present in the frozen `gemstack-test-matrix`.
+
+If any formula check fails or counts diverge, `gemstack verify` immediately halts with a `CLOSURE_RECONCILIATION_FAILURE` finding.
+
+---
+
+## 7. Structured Closure Manifest (`closure.json`)
+
+The closure manifest is an evidence snapshot stored at `specs/<feature>/closure.json`. It is a derived artifact produced strictly by the evidence collection step and never hand-authored.
+
+### Schema Direction:
+```json
+{
+  "$schema": "https://gemstack.dev/schemas/closure-v1.json",
+  "version": "1.0",
+  "feature_directory": "specs/007-mechanical-test-matrix-closure-evidence/",
+  "generated_at": "2026-09-11T12:00:00.000Z",
+  "status": "VERIFIED",
+  "closure_context": {
+    "closure_context_hash": "a1b2c3d4e5f67890abcdef1234567890abcdef1234567890abcdef1234567890",
+    "repository_type": "git",
+    "git_commit": "26db5c93c39aa2b5a1df97906eb46bc37894c214",
+    "working_tree_clean": true,
+    "relevant_files_digest": "d1e2f3a4b5c6..."
+  },
+  "acceptance_signature": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+  "canonical_summary": {
+    "required_total": 20,
+    "required_passed": 20,
+    "supplemental_total": 0,
+    "supplemental_passed": 0
+  },
+  "physical_summary": {
+    "supporting_total": 5,
+    "supporting_passed": 5,
+    "total_executed": 25,
+    "total_passed": 25,
+    "total_failed": 0,
+    "total_skipped": 0
+  },
+  "reconciliation": {
+    "math_valid": true,
+    "phantoms_detected": 0,
+    "orphans_detected": 0,
+    "missing_canonical_ids": []
+  },
+  "task_traceability_summary": {
+    "tasks_total": 17,
+    "tasks_with_validation": 15,
+    "tasks_documentation_only": 2,
+    "unmapped_canonical_tests": []
+  },
+  "required_gates": {
+    "ARCHITECTURE_CONSISTENCY_PASS": "PASS",
+    "CANONICAL_MATRIX_VALID": "PASS",
+    "ALL_REQUIRED_CANONICAL_MAPPED": "PASS",
+    "ALL_REQUIRED_CANONICAL_EXECUTED": "PASS",
+    "ALL_REQUIRED_CANONICAL_PASSED": "PASS",
+    "NO_PHANTOM_TESTS": "PASS",
+    "NO_ORPHAN_CANONICAL_BINDINGS": "PASS",
+    "TASK_TRACEABILITY_COMPLETE": "PASS",
+    "EXACT_RECONCILIATION_PASS": "PASS",
+    "EVIDENCE_FRESHNESS_VERIFIED": "PASS",
+    "CLOSURE_CONTEXT_RESOLVED": "PASS",
+    "REQUIRED_PROJECT_GATES_PASS": "PASS"
+  },
+  "supplemental_gates": {},
+  "exceptions": [],
+  "evidence_sources": [
+    {
+      "command": "node --test tests/**/*.test.js",
+      "runner": "node:test",
+      "exit_code": 0,
+      "duration_ms": 420,
+      "environment": {
+        "node_version": "v20.18.0",
+        "os": "win32",
+        "arch": "x64"
+      }
+    }
+  ],
+  "blockers": [],
+  "warnings": []
+}
+```
+
+### Optional Git Metadata & Worktree Cleanness:
+- Git is NOT a mandatory closure authority. If `.git` does not exist, `git_commit: null` and `working_tree_clean: null`.
+- When Git is present, `working_tree_clean: true | false` is recorded as diagnostic metadata.
+- A dirty working tree is NOT an inherent blocker. The closure context simply binds deterministically to the dirty state that was physically tested.
+
+---
+
+## 8. Deterministic Closure Context & Freshness (`closureContextHash`)
+
+Evidence is only valid for the exact project state against which it was collected. To prevent whole-repository scanning, the closure context is formed from a deterministic structured object:
+
+```json
+{
+  "repositoryContext": "<HEAD_SHA_or_null>",
+  "worktreeClean": true,
+  "phaseHashes": {
+    "spec": "<sha256>",
+    "plan": "<sha256>",
+    "tasks": "<sha256>"
+  },
+  "acceptanceSignature": "<sha256>",
+  "testFilesHash": "<sha256_of_executed_test_files>",
+  "implementationContextHash": "<sha256_of_bound_implementation_files>"
+}
+```
+
+$$\text{closureContextHash} = \text{SHA-256}(\text{canonical_json_serialization}(\text{contextObject}))$$
+
+### Relevant File Scope Determination:
+- Phase artifacts (`spec.md`, `plan.md`, `tasks.md`).
+- Test matrix `acceptanceSignature`.
+- Declared physical test files identified by runner execution.
+- Implementation-relevant files explicitly derived from `tasks.md` task-to-file bindings (or minimal safe mappings defined in `plan.md`).
+- Entire repository recursive scanning is strictly avoided.
+
+### Read-Only Freshness Validation (`gemstack verify`):
+- `gemstack verify` recomputes the current `closureContextHash` in-memory without modifying any files.
+- If the computed hash differs from `closure.json`, the status is `STALE` and verification emits `CLOSURE_EVIDENCE_STALE`.
+- `gemstack verify` NEVER mutates or regenerates `closure.json` to make stale evidence fresh.
+
+---
+
+## 9. Test Runner Adapter & Execution Architecture
+
+1. **Native Runner Integration**: Gemstack interfaces with native runners via standardized adapters (dogfooding built-in `node:test` via `node --test`).
+2. **Zero Dependencies**: Subprocess execution uses Node.js standard library `node:child_process` (`spawn` or `execFile` with explicit argument arrays, preventing shell quoting bugs and glob expansion discrepancies).
+3. **MVP Scope**:
+   - `node:test`: Fully supported first-class adapter capturing structured execution results.
+   - Generic command exit-code gate: Fully supported for standard build/lint/typecheck commands.
+   - Vitest / Playwright: Forward-compatible adapter contracts defined without requiring immediate introspection implementation.
+4. **Trace Extraction**: Structured native output formats (e.g. `--test-reporter=tap` or `--test-reporter=spec`) are parsed for test names and canonical IDs embedded in titles (`[TEST-CLOSURE-xxx]`).
+
+---
+
+## 10. Operational Command Separation: Collect vs. Verify vs. Ship
+
+- **Evidence Collection (`COLLECT`)**: Runs configured test commands, captures runner execution traces, reconciles counts, and generates/regenerates `closure.json`. This responsibility belongs to the pre-ship preparation workflow (e.g. `gemstack ship --collect` or review/qa skills). A new command `gemstack close` is NOT needed at this stage because collection maps cleanly to existing lifecycle flows.
+- **Verification (`VERIFY`)**: `gemstack verify` is strictly read-only (`VERIFY = VALIDATE`). It reads `closure.json`, validates gates, checks freshness against current `closureContextHash`, and reports findings without modifying disk state.
+- **Shipping (`SHIP`)**: Validates that evidence status is `VERIFIED` (or policy-permitted `VERIFIED_WITH_EXCEPTIONS`) and that evidence is fresh, before performing human-approved phase transition.
+
+---
+
+## 11. Closure Gates & State Transitions
+
+### Formal Closure States:
+- `NOT_EVALUATED`: No closure evidence collected yet.
+- `BLOCKED`: One or more REQUIRED gates failed, or evidence is inconsistent/missing.
+- `VERIFIED`: All REQUIRED gates passed with zero exceptions.
+- `VERIFIED_WITH_EXCEPTIONS`: All REQUIRED gates passed, with approved non-blocker exceptions explicitly waived with human approval.
+- `STALE`: Bound source or test files changed after evidence collection.
+
+### Required Mechanical Gates (`REQUIRED`):
+1. `ARCHITECTURE_CONSISTENCY_PASS`: Zero open blockers from Upgrade A consistency engine.
+2. `CANONICAL_MATRIX_VALID`: `gemstack-test-matrix` schema, IDs, and syntax valid.
+3. `ALL_REQUIRED_CANONICAL_MAPPED`: Every required test bound to an implementation task.
+4. `ALL_REQUIRED_CANONICAL_EXECUTED`: Exact set equality between expected and executed required IDs.
+5. `ALL_REQUIRED_CANONICAL_PASSED`: All executed required tests passed.
+6. `NO_PHANTOM_TESTS`: Zero claimed tests absent from physical runner output.
+7. `NO_ORPHAN_CANONICAL_BINDINGS`: Zero physical tests claiming undeclared canonical IDs.
+8. `TASK_TRACEABILITY_COMPLETE`: All tasks with `validation_required: true` have valid test bindings.
+9. `EXACT_RECONCILIATION_PASS`: Mathematical count equation balances perfectly.
+10. `EVIDENCE_FRESHNESS_VERIFIED`: `closureContextHash` matches current working tree state.
+11. `CLOSURE_CONTEXT_RESOLVED`: Context hash successfully computed across git or non-git environment.
+12. `REQUIRED_PROJECT_GATES_PASS`: All explicitly configured project commands (e.g. build, lint) exited with code 0.
+
+### Required Project Gates Canonical Sources:
+Project-specific required commands must be sourced from trusted configuration:
+- Structured feature metadata (`specs/<feature>/.gemstack.json`).
+- Gemstack configuration file (`.gemstackrc` or `gemstack.config.json`).
+- Explicit trusted `package.json` scripts referenced in `plan.md`.
+
+### Accepted Exceptions & Non-Waivable Classes:
+The following blocker classes are strictly **NON-WAIVABLE**:
+- `TEST_MATRIX_PARSE_ERROR`
+- `TEST_MATRIX_DUPLICATE_ID`
+- `TEST_MATRIX_INVALID_SHAPE`
+- `ACCEPTANCE_SIGNATURE_MISMATCH`
+- `PHANTOM_TEST` (fictitious evidence is never acceptable)
+- `CLOSURE_EVIDENCE_STALE`
+- `CLOSURE_EVIDENCE_INCONSISTENT`
+
+Potentially waivable only via explicit human approval bound to `contextHash`:
+- Specific `REQUIRED_GATE_FAILED` or `REQUIRED_TEST_SKIPPED` under formal waiver.
+- Waiving an exception does NOT convert a failure to PASS; it marks the feature `VERIFIED_WITH_EXCEPTIONS`.
+
+---
+
+## 12. Complete Canonical Error and Finding Codes (Upgrade B)
+
+Upgrade B defines a dedicated, non-redundant error taxonomy sharing Upgrade A fingerprint primitives:
+- `TEST_MATRIX_PARSE_ERROR`
+- `TEST_MATRIX_DUPLICATE_ID`
+- `TEST_MATRIX_INVALID_SHAPE`
+- `ACCEPTANCE_SIGNATURE_MISMATCH` (matrix signature inconsistent with approved artifact)
+- `REQUIRED_TEST_MISSING` (canonical requirement has no physical implementation)
+- `REQUIRED_TEST_NOT_EXECUTED` (physical test exists but was not invoked in runner run)
+- `REQUIRED_TEST_FAILED` (executed canonical test threw an assertion or error)
+- `REQUIRED_TEST_SKIPPED` (required test bypassed by runner skip directive)
+- `PHANTOM_TEST` (claimed test not found in physical runner output)
+- `ORPHAN_TEST` (physical test claims an undeclared canonical ID)
+- `DUPLICATE_TEST_BINDING` (multiple distinct tasks claiming conflicting ownership)
+- `TASK_VALIDATION_MISSING` (task has `validation_required: true` without test bindings)
+- `UNMAPPED_CANONICAL_TEST` (canonical test has no task bound to it)
+- `CLOSURE_RECONCILIATION_FAILURE` (test count arithmetic equation fails to balance)
+- `REQUIRED_GATE_MISSING` (configured required gate command not found)
+- `REQUIRED_GATE_FAILED` (configured required gate command exited non-zero)
+- `CLOSURE_EVIDENCE_STALE` (code changed after closure manifest was generated)
+- `CLOSURE_EVIDENCE_INCONSISTENT` (closure manifest contents contradict runner evidence)
+
+---
+
+## 13. Legacy Mode & Progressive Adoption
+
+- Specs created under earlier versions (001–006) without a `gemstack-test-matrix` block operate in **Legacy Progressive Mode**.
+- In Legacy Mode, `gemstack verify` issues an informational notice (`LEGACY_SPEC_NO_TEST_MATRIX`) and does not enforce canonical ID reconciliation or block shipping, preserving 100% backward compatibility.