gemstack-ai 1.4.0 → 2.0.0

package/specs/013-gemstack-2.0-adaptable-sdd/context-capsule.json

@@ -0,0 +1,227 @@
+{
+  "$schema": "https://gemstack.dev/schemas/context-capsule-v1.json",
+  "acceptance_matrix": {
+    "canonical_ids": [
+      "TEST-AMEND-D01",
+      "TEST-AMEND-D02",
+      "TEST-AMEND-D03",
+      "TEST-DELTA-B01",
+      "TEST-DELTA-B02",
+      "TEST-DELTA-B03",
+      "TEST-MERGE-C01",
+      "TEST-MERGE-C02",
+      "TEST-MERGE-C03",
+      "TEST-RIGOR-A01",
+      "TEST-RIGOR-A02",
+      "TEST-RIGOR-A03",
+      "TEST-RIGOR-A04"
+    ],
+    "signature": "6ae546034e43677a9ce51b451415db890d27b57e36df3163286897fcd6720e07",
+    "total_required": 13
+  },
+  "architecture_summary": {
+    "core_purpose": "Deterministic context compression and safe continuation for AI-assisted engineering.",
+    "critical_boundaries": [
+      "Capsule is strictly derived, never authoritative",
+      "Semantic constraint losslessness: MUST/MUST NOT survive compression",
+      "Verification is read-only and never regenerates capsules"
+    ]
+  },
+  "canonical_invariants": [
+    {
+      "id": "INV-001",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-002",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-003",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-004",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-005",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-006",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-007",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-008",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-009",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-010",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-011",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-012",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    },
+    {
+      "id": "INV-013",
+      "normative": "MUST",
+      "rule": "\"gate\": \"REQUIRED\"",
+      "source_ref": "spec.md#4"
+    }
+  ],
+  "deferred_items": [
+    "Autonomous cross-repo capsule federations (out of scope)",
+    "LLM narrative fine-tuning (non-authoritative)"
+  ],
+  "frozen_contracts": [
+    {
+      "id": "formal-contract-amendment",
+      "type": "ENUM_SET",
+      "value": true
+    },
+    {
+      "id": "incremental-spec-deltas",
+      "type": "ENUM_SET",
+      "value": true
+    },
+    {
+      "id": "sdd-rigor-levels",
+      "type": "ENUM_SET",
+      "value": true
+    },
+    {
+      "id": "spec-conflict-detector",
+      "type": "BOOLEAN_INVARIANT",
+      "value": true
+    }
+  ],
+  "generated_at": "2026-09-23T02:29:29.366Z",
+  "generator": {
+    "name": "gemstack",
+    "version": "1.2.0"
+  },
+  "historical_context": [
+    {
+      "feature": "specs/006-architecture-consistency-engine",
+      "key_guarantees": [
+        "Anti-loop findings",
+        "Deterministic hashing",
+        "Frozen contracts"
+      ],
+      "status": "CLOSED"
+    },
+    {
+      "feature": "specs/007-mechanical-test-matrix-closure-evidence",
+      "key_guarantees": [
+        "Mechanical test matrix",
+        "VERIFY = VALIDATE",
+        "closure.json evidence"
+      ],
+      "status": "CLOSED"
+    },
+    {
+      "feature": "specs/008-cost-provider-safety-gates",
+      "key_guarantees": [
+        "Fail-closed gates",
+        "NO PROOF = NO EXECUTION",
+        "Zero network verify"
+      ],
+      "status": "CLOSED"
+    }
+  ],
+  "project": {
+    "active_feature": "specs/013-gemstack-2.0-adaptable-sdd",
+    "current_phase": "shipped",
+    "lifecycle_status": "SHIPPED",
+    "name": "gemstack-ai",
+    "next_permitted_phase": "PLAN"
+  },
+  "provenance": {
+    "source_set_hash": "d4707b57238b7461acbd3809b03d09a676ca98b796108ec60da512ed51f61275",
+    "sources": [
+      {
+        "hash": "eaf7d2b071dccf4422b57109ef6ee76637e40c0a7d27e2868c3f26f76ea681cb",
+        "path": ".gemstack/state.json",
+        "role": "LIFECYCLE_STATE"
+      },
+      {
+        "hash": "484cdcb089ee6a2950ddd3e7a9d7ebe22585c058566a8699392f97f2753e8737",
+        "path": "specs/013-gemstack-2.0-adaptable-sdd/closure.json",
+        "role": "CLOSURE_EVIDENCE"
+      },
+      {
+        "hash": "8be9cb72e649dbdc53819c8fac9029fc73241d7c267e3ff596e0104927a1b5c1",
+        "path": "specs/013-gemstack-2.0-adaptable-sdd/plan.md",
+        "role": "PLAN"
+      },
+      {
+        "hash": "32f326f279a7083e67bd3b386597718c203abbcca99f71d8426b50ca3616d93d",
+        "path": "specs/013-gemstack-2.0-adaptable-sdd/spec.md",
+        "role": "SPECIFICATION"
+      },
+      {
+        "hash": "843f2d12bf20c0ba844f0b7979aeb9b829faba32b2bcc04aa67f254126ceb9c4",
+        "path": "specs/013-gemstack-2.0-adaptable-sdd/tasks.md",
+        "role": "TASKS"
+      }
+    ]
+  },
+  "relevant_files": [
+    "src/commands/context.js",
+    "src/lib/context-capsule.js",
+    "tests/context-determinism.test.js"
+  ],
+  "schema_version": 1,
+  "tasks_state": {
+    "active_task_ids": [
+      "TASK-001",
+      "TASK-002",
+      "TASK-003",
+      "TASK-004",
+      "TASK-005",
+      "TASK-006"
+    ],
+    "completed": 0,
+    "in_progress": "TASK-001",
+    "total": 6
+  },
+  "unresolved_blockers": []
+}

package/specs/013-gemstack-2.0-adaptable-sdd/plan.md

@@ -0,0 +1,179 @@
+# Implementation Plan: Gemstack 2.0 Sprint C — Adaptable SDD & Incremental Specs
+
+**Feature ID:** `013-gemstack-2.0-adaptable-sdd`  
+**Phase:** `plan`  
+**Parent Release:** `gemstack-ai@2.0.0-alpha`
+
+---
+
+## 1. Inherited Architecture Contracts
+
+```gemstack-inherited-contracts
+[
+  {
+    "id": "sdd-rigor-levels",
+    "type": "ENUM_SET",
+    "values": [
+      "quick",
+      "fix",
+      "feature",
+      "high-risk"
+    ]
+  },
+  {
+    "id": "incremental-spec-deltas",
+    "type": "ENUM_SET",
+    "values": [
+      "added",
+      "modified",
+      "removed"
+    ]
+  },
+  {
+    "id": "spec-conflict-detector",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true
+  },
+  {
+    "id": "formal-contract-amendment",
+    "type": "ENUM_SET",
+    "values": [
+      "amendment-id",
+      "contract-id",
+      "version",
+      "reason",
+      "approved-by",
+      "signature"
+    ]
+  }
+]
+```
+
+---
+
+## 2. Technical Architecture & Modules
+
+### 2.1 Rigor Engine (`src/lib/sdd-rigor.js`)
+- `detectRigorLevel(specContent)`: Extracts declared rigor level from frontmatter or document metadata (`rigor: quick | fix | feature | high-risk`, default: `feature`).
+- `validateRigorRequirements(rigorLevel, context)`:
+  - `quick`: Requires single valid artifact (`quick.md` or `spec.md`). Does not require `plan.md` or `tasks.md`.
+  - `fix`: Requires test matrix with at least one regression test (`category: REGRESSION` or ID containing `REG`).
+  - `feature`: Standard 3-phase SDD with full `plan.md`, `tasks.md`, and complete traceability.
+  - `high-risk`: Must include explicit Threat Model, Rollback Plan, and 2 distinct human approval signatures in sidecar (`approvals: [{ approver, signature, timestamp }, ...]`).
+
+### 2.2 Incremental Spec Engine (`src/lib/spec-delta.js`)
+- `parseSpecDelta(deltaContent)`: Parses structured delta declarations containing `ADDED`, `MODIFIED`, and `REMOVED` sections for contracts, requirements, and test matrices.
+- `applySpecDelta(baseSpec, delta)`: Applies diff onto base spec without clobbering unmentioned baseline requirements. Fails closed with `DELTA_TARGET_NOT_FOUND` if modifying a non-existent item.
+
+### 2.3 Spec Conflict & Merge Engine (`src/lib/spec-merge.js`)
+- `detectSpecConflicts(specA, specB)`:
+  - Compares `gemstack-contracts` across both specs. Flags `CONTRACT_COLLISION` if the same contract ID exists with different types, values, or schemas.
+  - Compares `gemstack-test-matrix`. Flags `DUPLICATE_TEST_ID` if identical test IDs exist across both specs with divergent descriptions or layers.
+- `mergeSpecs(specA, specB)`: Produces merged spec when conflict checks pass cleanly.
+
+### 2.4 Contract Amendment Engine (`src/lib/contract-amendments.js`)
+- `computeAmendmentSignature(amendment, secret)`: Computes HMAC-SHA256 or SHA-256 over normalized amendment properties (`amendment_id`, `contract_id`, `version`, `reason`, `approved_by`).
+- `validateContractAmendments(upstreamContracts, currentContracts, amendments, options)`:
+  - Verifies that any contract modified or removed from upstream is justified by a valid, signed amendment record.
+  - Rejects unapproved or signature-mismatched amendments (`AMENDMENT_SIGNATURE_INVALID`).
+
+### 2.5 CLI Integration (`src/commands/spec.js` and `src/cli.js`)
+- `gemstack spec merge <targetSpecDir>`: Merges another spec directory or branch into active spec with automated conflict detection.
+- `gemstack spec validate`: Validates rigor compliance and amendment integrity.
+
+---
+
+## 3. Physical Test Bindings
+
+```gemstack-test-bindings
+[
+  {
+    "id": "TEST-RIGOR-A01",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Quick rigor level validates with single artifact without requiring plan/tasks"
+  },
+  {
+    "id": "TEST-RIGOR-A02",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Fix rigor level enforces presence of linked regression test in test matrix"
+  },
+  {
+    "id": "TEST-RIGOR-A03",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Feature rigor level enforces complete 3-phase SDD artifacts and closure manifest"
+  },
+  {
+    "id": "TEST-RIGOR-A04",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "High-risk rigor level fails closed without Threat Model, Rollback Plan, and 2 approvals"
+  },
+  {
+    "id": "TEST-DELTA-B01",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Parses and applies ADDED, MODIFIED, and REMOVED deltas onto a base spec"
+  },
+  {
+    "id": "TEST-DELTA-B02",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Preserves untouched baseline requirements and contracts when applying deltas"
+  },
+  {
+    "id": "TEST-DELTA-B03",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Fails closed when an incremental delta modifies or removes a non-existent item"
+  },
+  {
+    "id": "TEST-MERGE-C01",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Spec merge detects colliding contract IDs with divergent values or schemas"
+  },
+  {
+    "id": "TEST-MERGE-C02",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Spec merge detects colliding canonical test IDs declared across concurrent specs"
+  },
+  {
+    "id": "TEST-MERGE-C03",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Spec merge succeeds cleanly when contract sets and test IDs are disjoint or identical"
+  },
+  {
+    "id": "TEST-AMEND-D01",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Accepts contract modification only when accompanied by a valid formal amendment record"
+  },
+  {
+    "id": "TEST-AMEND-D02",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Rejects contract amendments that are unapproved or have invalid signatures"
+  },
+  {
+    "id": "TEST-AMEND-D03",
+    "file": "tests/adaptable-sdd-p1.test.js",
+    "symbol": "Verifies amendment integrity hash over amendment fields"
+  }
+]
+```
+
+---
+
+## 4. Mandatory Package Script Closure Gates
+
+```gemstack-closure-gates
+[
+  {
+    "id": "gate-test",
+    "type": "PACKAGE_SCRIPT",
+    "script": "test",
+    "requirement": "REQUIRED",
+    "waivable": false
+  },
+  {
+    "id": "gate-ci-all",
+    "type": "PACKAGE_SCRIPT",
+    "script": "ci:all",
+    "requirement": "REQUIRED",
+    "waivable": false
+  }
+]
+```

package/specs/013-gemstack-2.0-adaptable-sdd/spec.md

@@ -0,0 +1,212 @@
+# Specification: Gemstack 2.0 Sprint C — Adaptable SDD & Incremental Specs
+
+**Feature ID:** `013-gemstack-2.0-adaptable-sdd`  
+**Phase:** `spec`  
+**Parent Release:** `gemstack-ai@2.0.0-alpha`
+
+---
+
+## 1. Context & Objectives
+
+Gemstack's core strength is Spec-Driven Development (SDD) with strict frozen contracts. However, real-world development highlighted key friction points:
+1. **One-size-fits-all overhead**: A one-line cosmetic fix or documentation update required the full overhead of 3 separate artifacts (`spec.md` -> `plan.md` -> `tasks.md`).
+2. **High-risk blindness**: Critical architectural changes or auth refactors were treated with the same validation depth as regular features, lacking mandatory threat models or dual human sign-off.
+3. **Destructive spec overwrites in concurrent features**: Parallel branches modifying specs routinely clobbered baseline requirements instead of declaring incremental diffs (`ADDED`, `MODIFIED`, `REMOVED`).
+4. **Silent contract tampering vs. Audited amendments**: Contracts were either completely immutable or subject to uncontrolled modification without auditable justification and cryptographic approval.
+
+Sprint C resolves these challenges by introducing:
+- **Four Rigor Levels**: `quick`, `fix`, `feature`, and `high-risk`.
+- **Incremental Spec Deltas**: Structured `ADDED`, `MODIFIED`, and `REMOVED` declarations.
+- **Spec Merge & Conflict Detector**: `gemstack spec merge` to detect colliding contract IDs and canonical test IDs across branches.
+- **Auditable Contract Amendments**: Formal versioned amendments replacing silent mutations.
+
+---
+
+## 2. User Scenarios & Acceptance Criteria
+
+### User Story 1 — Flexible Rigor Levels (Priority: P1)
+As an engineer making a minor tweak or bugfix, I want an appropriate SDD rigor level so I can deliver safe code without unnecessary bureaucracy, while critical changes enforce maximum scrutiny.
+- **Scenario 1.1 (quick)**: A cosmetic change with `rigor: quick` is verified with a single concise artifact without blocking on missing `plan.md` or `tasks.md`.
+- **Scenario 1.2 (fix)**: A bugfix with `rigor: fix` requires a linked regression test (`REGRESSION` category or `REG` ID) that validates the fix.
+- **Scenario 1.3 (feature)**: A standard feature enforces the full 3-phase lifecycle.
+- **Scenario 1.4 (high-risk)**: A critical change fails closed unless it contains an explicit Threat Model, Rollback Plan, and 2 distinct human approval signatures.
+
+### User Story 2 — Incremental Spec Deltas (Priority: P1)
+As an agent or engineer building on an existing feature, I want to declare spec deltas (`ADDED`, `MODIFIED`, `REMOVED`) so that concurrent work doesn't clobber baseline requirements.
+- **Scenario 2.1**: An incremental delta successfully parses and overlays onto the base specification.
+- **Scenario 2.2**: Unmodified baseline requirements are preserved intact in the effective merged specification.
+- **Scenario 2.3**: Unmatched modifications fail closed with clear error messaging.
+
+### User Story 3 — Offline Spec Conflict & Collision Detection (Priority: P1)
+As a lead architect merging feature branches, I want `gemstack spec merge` to mechanically detect contract and test ID collisions before merging.
+- **Scenario 3.1**: Identifies colliding contract IDs with divergent values or schemas across branches and aborts.
+- **Scenario 3.2**: Detects duplicate canonical test IDs declared across concurrent specs.
+- **Scenario 3.3**: Merges cleanly when contract and test sets are disjoint or mutually consistent.
+
+### User Story 4 — Formal Contract Amendments (Priority: P1)
+As a security auditor, I want any change to a frozen architectural contract to require a formal, signed amendment record so that contract evolution is auditable and non-repudiable.
+- **Scenario 4.1**: Contract changes accompanied by a valid, approved amendment record pass verification.
+- **Scenario 4.2**: Unapproved, missing, or signature-mismatched amendments fail closed.
+- **Scenario 4.3**: Amendment integrity hash validates against canonical amendment fields.
+
+---
+
+## 3. Architecture Contracts
+
+```gemstack-contracts
+[
+  {
+    "id": "sdd-rigor-levels",
+    "type": "ENUM_SET",
+    "values": [
+      "quick",
+      "fix",
+      "feature",
+      "high-risk"
+    ],
+    "description": "Supported SDD rigor levels defining required artifacts, testing depth, and review requirements."
+  },
+  {
+    "id": "incremental-spec-deltas",
+    "type": "ENUM_SET",
+    "values": [
+      "added",
+      "modified",
+      "removed"
+    ],
+    "description": "Allowed delta actions for incremental spec declarations."
+  },
+  {
+    "id": "spec-conflict-detector",
+    "type": "BOOLEAN_INVARIANT",
+    "value": true,
+    "description": "Offline conflict detection detects colliding contract IDs and duplicate test IDs across branches or spec directories."
+  },
+  {
+    "id": "formal-contract-amendment",
+    "type": "ENUM_SET",
+    "values": [
+      "amendment-id",
+      "contract-id",
+      "version",
+      "reason",
+      "approved-by",
+      "signature"
+    ],
+    "description": "Mandatory fields for formal contract amendment records."
+  }
+]
+```
+
+---
+
+## 4. Mechanical Acceptance Matrix
+
+```gemstack-test-matrix
+[
+  {
+    "id": "TEST-RIGOR-A01",
+    "category": "RIGOR",
+    "layer": "UNIT",
+    "description": "Quick rigor level validates with single artifact without requiring plan/tasks when verified",
+    "pass_criteria": "validateRigorRequirements returns valid=true for quick spec with 1 artifact",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-RIGOR-A02",
+    "category": "RIGOR",
+    "layer": "UNIT",
+    "description": "Fix rigor level enforces presence of linked regression test in test matrix",
+    "pass_criteria": "Fails closed when fix spec has no regression test; passes when regression test is bound",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-RIGOR-A03",
+    "category": "RIGOR",
+    "layer": "UNIT",
+    "description": "Feature rigor level enforces complete 3-phase SDD artifacts and closure manifest",
+    "pass_criteria": "Rejects missing plan/tasks in feature mode; passes when full lifecycle is present",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-RIGOR-A04",
+    "category": "RIGOR",
+    "layer": "UNIT",
+    "description": "High-risk rigor level fails closed without Threat Model, Rollback Plan, and 2 distinct human approvals",
+    "pass_criteria": "Rejects high-risk spec missing threat model, rollback plan, or dual human signatures",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-DELTA-B01",
+    "category": "DELTA",
+    "layer": "UNIT",
+    "description": "Parses and applies ADDED, MODIFIED, and REMOVED deltas onto a base spec",
+    "pass_criteria": "Merged specification accurately reflects additions, modifications, and removals",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-DELTA-B02",
+    "category": "DELTA",
+    "layer": "UNIT",
+    "description": "Preserves untouched baseline requirements and contracts when applying incremental deltas",
+    "pass_criteria": "Baseline items not mentioned in delta remain intact in effective merged spec",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-DELTA-B03",
+    "category": "DELTA",
+    "layer": "UNIT",
+    "description": "Fails closed when an incremental delta modifies or removes a non-existent item",
+    "pass_criteria": "Throws DELTA_TARGET_NOT_FOUND error when target item does not exist in base",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-MERGE-C01",
+    "category": "MERGE",
+    "layer": "UNIT",
+    "description": "Spec merge detects colliding contract IDs with divergent values or schemas across branches",
+    "pass_criteria": "detectSpecConflicts flags CONTRACT_COLLISION with conflicting values",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-MERGE-C02",
+    "category": "MERGE",
+    "layer": "UNIT",
+    "description": "Spec merge detects colliding canonical test IDs declared across concurrent specs",
+    "pass_criteria": "detectSpecConflicts flags DUPLICATE_TEST_ID across merged specs",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-MERGE-C03",
+    "category": "MERGE",
+    "layer": "UNIT",
+    "description": "Spec merge succeeds cleanly when contract sets and test IDs are disjoint or identical",
+    "pass_criteria": "detectSpecConflicts returns conflicts=[] and valid=true for clean specs",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-AMEND-D01",
+    "category": "AMENDMENT",
+    "layer": "UNIT",
+    "description": "Accepts contract modification only when accompanied by a valid formal amendment record",
+    "pass_criteria": "validateContractAmendments approves modification with valid amendment; fails without it",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-AMEND-D02",
+    "category": "AMENDMENT",
+    "layer": "UNIT",
+    "description": "Rejects contract amendments that are unapproved or have invalid cryptographic signatures",
+    "pass_criteria": "Fails closed with AMENDMENT_SIGNATURE_INVALID on tampered signature",
+    "gate": "REQUIRED"
+  },
+  {
+    "id": "TEST-AMEND-D03",
+    "category": "AMENDMENT",
+    "layer": "UNIT",
+    "description": "Verifies amendment integrity hash over amendment fields (amendment_id, contract_id, reason)",
+    "pass_criteria": "computeAmendmentSignature matches expected SHA-256 digest over normalized fields",
+    "gate": "REQUIRED"
+  }
+]
+```