@hellraisercenobit/ai-engineering-gate 0.8.0

package/skills/engineering/transpose-modern-typescript/references/declaration.schema.json

@@ -0,0 +1,190 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/contracts/schemas/declaration.schema.json",
+  "title": "Dimension declaration 1.0.0",
+  "description": "One per registered dimension per task, written through `declare` before any decision record. It states whether the dimension applies, on which paths, for which request and under which constraints. A non-applicable dimension has a declaration and nothing else.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "document",
+    "documentVersion",
+    "dimension",
+    "applicability",
+    "reason",
+    "request",
+    "constraints",
+    "revision"
+  ],
+  "properties": {
+    "document": {
+      "const": "declaration"
+    },
+    "documentVersion": {
+      "const": "1.0.0"
+    },
+    "dimension": {
+      "description": "A dimension identifier the member manifest registers.",
+      "type": "string",
+      "minLength": 1
+    },
+    "applicability": {
+      "enum": [
+        "applicable",
+        "non-applicable"
+      ]
+    },
+    "reason": {
+      "description": "Why the dimension applies, or why it does not. Never empty: skipping a dimension is a recorded decision.",
+      "type": "string",
+      "minLength": 1
+    },
+    "request": {
+      "description": "The requester's own wording, without builder choices or rationale. The neutral brief is rendered from it.",
+      "type": "string",
+      "minLength": 1
+    },
+    "constraints": {
+      "description": "Factual constraints only: project targets, public contracts, independent sources. When tests are TypeScript, name the ES/compiler target as a factual string (example: compiler: TypeScript 4.0.5, target ES2015, lib es2015, strict off). A tsconfig path in scope.configuration is not a substitute. PHP and other non-TypeScript suites omit this constraint rather than invent one.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "base": {
+      "$ref": "#/$defs/base"
+    },
+    "scope": {
+      "$ref": "#/$defs/scope"
+    },
+    "revision": {
+      "$ref": "#/$defs/revision"
+    }
+  },
+  "$defs": {
+    "base": {
+      "description": "The comparison base. Required when the dimension applies; the change set is the diff from its merge-base with HEAD.",
+      "type": "string",
+      "minLength": 1
+    },
+    "scope": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "paths"
+      ],
+      "properties": {
+        "paths": {
+          "description": "Repository-relative file paths or directory prefixes the dimension protects.",
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "configuration": {
+          "description": "Repository-relative configuration files the decisions depend on. They enter the source fingerprint.",
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "revision": {
+      "description": "Same shape as a decision record's revision: revision 1 has no previous, a later one names it.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "number",
+        "previous",
+        "reason"
+      ],
+      "properties": {
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "previous": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "minLength": 1
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "number": {
+                "type": "integer",
+                "minimum": 2
+              }
+            },
+            "required": [
+              "number"
+            ]
+          },
+          "then": {
+            "properties": {
+              "previous": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "else": {
+            "properties": {
+              "previous": {
+                "type": "null"
+              }
+            }
+          }
+        }
+      ]
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "applicability": {
+            "const": "applicable"
+          }
+        },
+        "required": [
+          "applicability"
+        ]
+      },
+      "then": {
+        "required": [
+          "scope",
+          "base"
+        ],
+        "properties": {
+          "scope": {
+            "$ref": "#/$defs/scope"
+          },
+          "base": {
+            "$ref": "#/$defs/base"
+          }
+        }
+      },
+      "else": {
+        "properties": {
+          "scope": false,
+          "base": false
+        }
+      }
+    }
+  ]
+}

package/skills/engineering/transpose-modern-typescript/references/dispute.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/contracts/schemas/dispute.schema.json",
+  "title": "Dispute 1.0.0",
+  "description": "The builder's second and only other response to a finding, beside addressing it. It contests one finding with a pointer to counter-evidence that already exists; a dispute without such a pointer is refused. It goes to the user and its only exit is an arbitration.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "document",
+    "documentVersion",
+    "dimension",
+    "report",
+    "finding",
+    "counterEvidence",
+    "position"
+  ],
+  "properties": {
+    "document": {
+      "const": "dispute"
+    },
+    "documentVersion": {
+      "const": "1.0.0"
+    },
+    "dimension": {
+      "type": "string",
+      "minLength": 1
+    },
+    "report": {
+      "description": "The identifier of the report that carries the contested finding.",
+      "type": "string",
+      "minLength": 1
+    },
+    "finding": {
+      "description": "The contested finding's identifier.",
+      "type": "string",
+      "minLength": 1
+    },
+    "counterEvidence": {
+      "description": "Pointers to artifacts that exist now. Each path is checked; a dangling pointer refuses the dispute.",
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "path",
+          "claim"
+        ],
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1
+          },
+          "claim": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "position": {
+      "description": "The builder's position in one sentence.",
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}

package/skills/engineering/transpose-modern-typescript/references/evidence-append.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/contracts/schemas/evidence-append.schema.json",
+  "title": "Evidence append 1.0.0",
+  "description": "Append-only. Journal events, check outputs, snapshots and any artifact a record planned are filed through `evidence append`, never written into the gate's index by hand. The gate stamps every append with the content hashes of the record's planned artifacts, by role, so an event proves the state of test and production artifacts at the moment it was filed.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "document",
+    "documentVersion",
+    "dimension",
+    "record",
+    "kind",
+    "payload"
+  ],
+  "properties": {
+    "document": {
+      "const": "evidence-append"
+    },
+    "documentVersion": {
+      "const": "1.0.0"
+    },
+    "dimension": {
+      "type": "string",
+      "minLength": 1
+    },
+    "record": {
+      "description": "The decision record this evidence belongs to.",
+      "type": "string",
+      "minLength": 1
+    },
+    "kind": {
+      "description": "A kind the member's evidence schemas name, which then validates the payload, or one of the generic kinds.",
+      "type": "string",
+      "minLength": 1
+    },
+    "produces": {
+      "description": "The planned artifact this append produces or extends. A planned artifact is satisfied by a file in the worktree or by an append that names it here.",
+      "type": "string",
+      "minLength": 1
+    },
+    "payload": {
+      "description": "Opaque to the envelope. Validated against the member's evidence schema when its kind names one."
+    },
+    "filedAt": {
+      "description": "Stamped by the gate when the append is stored.",
+      "type": "string",
+      "minLength": 1
+    },
+    "artifactHashes": {
+      "description": "Stamped by the gate: the content hash of every artifact the record planned, grouped by role, at the moment of the append.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "builder": {
+      "description": "Stamped by the gate: the identity it captured for the caller.",
+      "type": "object"
+    },
+    "replayed": {
+      "description": "Stamped by the gate: `true` only when the gate itself ran the scenario through `replay`.",
+      "type": "boolean"
+    }
+  }
+}

package/skills/engineering/transpose-modern-typescript/references/idioms.md

@@ -0,0 +1,74 @@
+# Everyday idioms
+
+Apply MT-23 to every feature's actual target support.
+
+## MT-01 - Extract and construct values clearly
+
+**Intent/use:** repeated properties from the same stable object, tuples or parameters can
+use shallow destructuring; use shorthand, rest or spread when they express the exact shape
+with less bookkeeping. Prefer `const { id, name } = user` over repeated stable extractions.
+**Alternatives/trade-offs:** direct access preserves provenance; explicit copies expose a
+boundary. Destructuring defaults cover undefined, not null. Spread/rest copy own enumerable
+properties shallowly; they are not cloning or sanitizing arbitrary objects.
+**Avoid:** deep cryptic patterns, extracting a method that needs its receiver, changing getter
+count/order or reactive read timing. Do not blanket-destructure framework state.
+**Invariants:** identical values, identity/copy depth, property evaluation and receiver behavior.
+**Sources/support:** [destructuring](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring),
+[spread](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax);
+check syntax transforms and the project's reactivity contract.
+
+## MT-02 - Default only for the intended absence
+
+**Intent/use:** choose `value ?? fallback` when only null/undefined mean absent; remove verbose
+nullish ternaries. Preserve 0, false and empty string.
+**Alternatives/trade-offs:** `||` is correct for deliberate falsy fallback; a destructuring
+default applies only to undefined. Explicit branching is appropriate when outcomes differ.
+**Avoid:** replacing a domain truthiness rule mechanically, hiding required data, or changing
+fallback laziness. Parenthesize mixtures with logical operators as required by the grammar.
+**Invariants:** test null, undefined, 0, false and empty string against the original contract.
+**Source/support:** [nullish coalescing](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing);
+parser/transpiler support is separate from library APIs.
+
+## MT-03 - Initialize a mutable location once
+
+**Intent/use:** `state.items ??= createItems()` expresses intentional nullish initialization.
+**Alternatives/trade-offs:** explicit condition for distinct null/undefined cases; immutable
+replacement when ownership forbids mutation. A getter/setter is observable code.
+**Avoid:** `||=` if false/0/empty string is valid; eager fallback construction; assuming
+`x ??= y` and `x = x ?? y` have the same setter behavior.
+**Invariants:** existing collection identity survives; default is lazy; target evaluation
+and setter calls match the intended contract; mutation is owned by this operation.
+**Source/support:** [nullish assignment](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Nullish_coalescing_assignment);
+check build transform and access effects.
+
+## MT-04 - Chain genuinely optional access
+
+**Intent/use:** choose `object?.property`, `callback?.()`, `items?.[index]` or
+`items?.[index]?.label` when the corresponding location may legitimately be absent.
+**Alternatives/trade-offs:** required data uses validation or an explicit failure; a branch
+can distinguish absence causes. `items?.map(f) ?? []` is valid only if absent and empty
+collections mean the same thing. Optional calls still require a callable present value.
+**Avoid:** masking a required item, treating optional chaining as external-data validation,
+losing receiver binding or changing side effects in index/call arguments.
+**Invariants:** container/element/property absence are separate; index zero and empty arrays
+work; required absence still fails; short-circuit effects remain intentional.
+**Source/support:** [optional chaining](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Optional_chaining);
+check parser/transpiler and framework reads.
+
+## MT-05 - Use a collection operation that states the result
+
+**Intent/use:** examine find/some/every for early termination, flatMap for zero-to-many
+results, entries/fromEntries/hasOwn for object operations, groupBy for grouping,
+toSorted/toReversed/toSpliced/with for non-mutating array changes and native Set operations.
+**Alternatives/trade-offs:** loops and reduce are sound for combined passes, custom state or
+clearer control flow. Avoid a chain that creates unnecessary arrays. A transparent helper
+may disappear only after MT-19's public/domain contract check.
+**Avoid:** equating grouping with arbitrary aggregation; changing sparse-array visitation,
+mutation, duplicate order, key coercion or missing-group behavior. Object.groupBy returns a
+null-prototype object with property keys; Map.groupBy preserves arbitrary key identity.
+**Invariants:** output values/order/keys, duplicate policy, own-property/prototype semantics,
+input mutation and empty/missing cases match the contract.
+**Sources/support:** [array methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array),
+[Object.groupBy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/groupBy),
+[Map.groupBy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/groupBy).
+Check each method, not just Array/Map support.

package/skills/engineering/transpose-modern-typescript/references/marker.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/contracts/schemas/marker.schema.json",
+  "title": "Suite marker 1.0.0",
+  "description": "Committed at the repository root as `.ai-engineering-suite.json`. Its presence is the project's opt-in and the only signal enforcement reads: without it every gate command allows and prints nothing that blocks.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "markerVersion",
+    "dimensions"
+  ],
+  "properties": {
+    "markerVersion": {
+      "const": "1.0.0"
+    },
+    "dimensions": {
+      "description": "`all` registers every member of the manifest; a list registers exactly those dimension identifiers.",
+      "oneOf": [
+        {
+          "const": "all"
+        },
+        {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      ]
+    },
+    "evidenceRoot": {
+      "description": "Overrides the default evidence root. `~` expands to the user's home directory. A relative path resolves against the repository root, which the change set then excludes.",
+      "type": "string",
+      "minLength": 1
+    },
+    "exportDirectory": {
+      "description": "Repository-relative directory `export` writes to. Excluded from the change set and from every fingerprint.",
+      "type": "string",
+      "minLength": 1
+    },
+    "ignore": {
+      "description": "Repository-relative glob patterns removed from the change set. `*` matches within one segment, `**` across segments.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "base": {
+      "description": "Default comparison base when a declaration names none.",
+      "type": "string",
+      "minLength": 1
+    },
+    "conflictRoundCap": {
+      "description": "Consecutive cross-dimension conflict rounds before `can-review` is refused with `arbitration-required`.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "roundCap": {
+      "description": "Total review rounds for one task before completion ends with `round-cap-reached`.",
+      "type": "integer",
+      "minimum": 1
+    },
+    "allowReplay": {
+      "description": "`false` forbids the gate-executed replay remedy, leaving a rerun of a full cycle as the only remedy for chronology-bound evidence.",
+      "type": "boolean"
+    },
+    "requireVerifiedIdentity": {
+      "description": "`true` refuses an attestation stored `identity-unverified`, for harnesses that provide agent identifiers.",
+      "type": "boolean"
+    }
+  }
+}

package/skills/engineering/transpose-modern-typescript/references/platform.md

@@ -0,0 +1,147 @@
+# Native platform capabilities
+
+Apply MT-23 per API and target: browser, worker, server and secure-context support differ.
+Native does not mean interchangeable with a library. Each rule compares the existing
+contract before replacing a mechanism.
+
+## MT-09 - Express asynchronous coordination and cancellation
+
+**Intent/use:** choose async/await and Promise combinators by failure/concurrency semantics.
+Promise.withResolvers suits bridging an externally settled operation when that lifecycle
+is real; AbortController/AbortSignal can propagate cancellation across supporting APIs.
+**Alternatives/trade-offs:** a plain async function or Promise constructor may suffice.
+Bound concurrency for resource-limited work; Promise.all starts no tasks by itself and
+does not cancel losing operations. AbortSignal.any/timeout need their own support checks.
+**Avoid:** exposed resolvers without settlement ownership, unhandled rejections, races
+mistaken for cancellation, or cleanup only on success.
+**Invariants:** correct success/failure/abort results; release listeners/resources on all
+exit paths; aborted work cannot publish a stale result.
+**Sources:** [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise),
+[withResolvers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/withResolvers),
+[AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal).
+
+## MT-10 - Consume network data with its actual flow contract
+
+**Intent/use:** Fetch, Request/Response, Headers and FormData replace redundant HTTP
+plumbing; Readable/Transform/WritableStream suit progressive producers and consumers.
+**Alternatives/trade-offs:** a mature client can carry retries, auth, caching and validation;
+buffering small atomic data is legitimate. Backpressure depends on producer cooperation.
+**Avoid:** forgetting fetch HTTP-status checks, consuming a body twice, retrying a
+non-replayable stream, or canceling a consumer without handling the producer.
+**Invariants:** response/errors/status handling preserved; ownership of body/reader locks,
+abort and cleanup explicit; partial consumption does not silently buffer the whole input.
+**Sources:** [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch),
+[Streams](https://developer.mozilla.org/en-US/docs/Web/API/Streams_API).
+Check the exact runtime's fetch/stream and upload behavior.
+
+## MT-11 - Use standard parsing and text services for standard formats
+
+**Intent/use:** URL/URLSearchParams for URLs and query data, Intl for locale-aware operations,
+TextEncoder/TextDecoder for byte/text boundaries.
+**Alternatives/trade-offs:** business grammars and nonstandard encodings may require a
+library; URL normalization and locale output can differ from manual strings.
+**Avoid:** treating URL parsing as destination authorization, interpolating unencoded query
+data, or asserting identical locale output across engines without that requirement.
+**Invariants:** origin/base, duplicate/empty query values, locale/time zone and encoding
+error policy are explicit; security checks survive helper removal.
+**Sources:** [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL),
+[Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl),
+[Encoding](https://developer.mozilla.org/en-US/docs/Web/API/Encoding_API).
+Check exact Intl features and deployed locale data.
+
+## MT-12 - Make copy and transfer ownership explicit
+
+**Intent/use:** structuredClone for supported structured values; ArrayBuffer, typed arrays
+and Blob for binary data; transfer ownership when it avoids a meaningful copy.
+**Alternatives/trade-offs:** shallow spread, serialization or domain-specific copying can
+be the right contract. A transfer's sender loses access to that transferable resource.
+**Avoid:** treating JSON serialization as a general clone, expecting functions/prototypes
+to survive structured cloning, transferring a buffer still owned by another consumer.
+**Invariants:** supported data types, identity, copy depth and source usability are tested;
+serialization format is deliberate; no unsupported universal performance claim.
+**Sources:** [structuredClone](https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone),
+[transferables](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects).
+Check API availability in the actual execution context.
+
+## MT-13 - Let the browser observe and manage browser state
+
+**Intent/use:** EventTarget options (signal/once/passive), event delegation, Intersection/
+Resize/MutationObserver, requestAnimationFrame, Web Animations and semantic HTML controls
+can remove custom listener/polling/rendering mechanisms.
+**Alternatives/trade-offs:** framework effects own DOM/state lifetime; polling can be
+necessary where observation semantics do not cover the requirement. Observers notify
+according to their own timing, not as a synchronous query replacement.
+**Avoid:** DOM writes outside framework ownership, passive listeners calling preventDefault,
+observer feedback loops, inaccessible custom controls or forgotten disconnect/abort/cancel.
+**Invariants:** correct event/notification timing, accessibility, cleanup and no stale work
+after disposal. rAF aligns visual work; it is not a guaranteed background scheduler.
+**Sources:** [addEventListener](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener),
+[IntersectionObserver](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API),
+[ResizeObserver](https://developer.mozilla.org/en-US/docs/Web/API/Resize_Observer_API),
+[MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver),
+[Web Animations](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API).
+Check exact options/components and framework lifecycle.
+
+## MT-14 - Choose scheduling by responsiveness and ownership
+
+**Intent/use:** workers, message channels, transferable data or supported task scheduling
+can move/split demonstrably blocking work.
+**Alternatives/trade-offs:** startup, serialization and coordination can exceed small work;
+task chunks on the main thread may suffice. Scheduler APIs require specific target checks.
+**Avoid:** synchronous yield or a microtask loop claimed to guarantee rendering time,
+worker use where direct DOM access is required, unbounded queued messages.
+**Invariants:** responsive observable flow, cancellation/termination, data ownership and
+error propagation; measured speed claims include startup/transfer costs.
+**Sources:** [workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers),
+[Scheduler](https://developer.mozilla.org/en-US/docs/Web/API/Scheduler).
+
+## MT-15 - Match persistence and coordination guarantees
+
+**Intent/use:** IndexedDB for structured transactional storage, Cache Storage for request/
+response caching, BroadcastChannel for cross-context messages and Web Locks for supported
+origin-scoped coordination.
+**Alternatives/trade-offs:** small synchronous storage or a server may satisfy a simpler/
+stronger contract; quotas, eviction, partitioning and private-mode behavior matter.
+**Avoid:** claiming durable delivery from broadcast, treating cache storage as a transactional
+database, assuming a lock spans servers/devices, or blocking UI with large synchronous writes.
+**Invariants:** consistency, error/eviction behavior, transaction lifetime and cleanup are
+explicit; persistence guarantees are no stronger than the actual environment.
+**Sources:** [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API),
+[CacheStorage](https://developer.mozilla.org/en-US/docs/Web/API/CacheStorage),
+[BroadcastChannel](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API),
+[Web Locks](https://developer.mozilla.org/en-US/docs/Web/API/Web_Locks_API).
+Check secure contexts, worker exposure and supported versions separately.
+
+## MT-16 - Use security primitives for their precise guarantee
+
+**Intent/use:** Web Crypto for appropriate cryptographic randomness/operations and textContent
+or native text insertion for plain text.
+**Alternatives/trade-offs:** a vetted library is appropriate when native algorithms/formats
+do not cover the protocol; rich HTML requires a deliberate sanitization/trusted-content policy.
+**Avoid:** Math.random for security-sensitive tokens, handwritten cryptography, URL parsing
+or type brands mistaken for validation/authorization, plain text routed through innerHTML.
+**Invariants:** the threat-relevant contract survives refactoring; randomness/algorithm/
+encoding and trust boundaries are explicit; no broad safety claim from API choice alone.
+**Sources:** [Web Crypto](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API),
+[textContent](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent).
+Check algorithm and secure-context support, not only the crypto global.
+## MT-25 - A wrapper around a platform capability needs a reason beyond its name
+
+**Intent/use:** a helper that forwards to a platform or language capability, adding no
+behavior, gives the reader one more indirection and one more thing to keep in step. Admit such
+a wrapper only for a reason that outlives the rename: domain semantics the capability does not
+carry, a compatibility policy the project owns in one place, instrumentation, lifecycle control
+the caller must not manage, or a stable project boundary a future migration crosses once.
+**Alternatives/trade-offs:** call the capability directly; a named domain function that
+computes something is not a wrapper; a thin adapter at a real boundary is one of the reasons
+above and records which one. When the reason is compatibility or instrumentation, the record
+names what the wrapper decides that its callers must not.
+**Avoid:** a function whose body is a single forwarding call with the arguments unchanged and
+no reason on record, a wrapper whose only argument is discoverability or house style, a
+project alias for a global, and a wrapper introduced together with the transposition that
+replaced the code it was meant to hide.
+**Invariants:** the record names the admitted reason for every retained or added wrapper, and
+what it would take to remove it; a wrapper with no admitted reason is removed by the change,
+not documented.
+**Sources:** [Web APIs](https://developer.mozilla.org/en-US/docs/Web/API),
+[Node API](https://nodejs.org/api/), the project's own compatibility record.