@hellraisercenobit/ai-engineering-gate 0.8.0

package/skills/engineering/transpose-testing-patterns/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-testing-patterns/references/detect-adapter.mjs

@@ -0,0 +1,98 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function inspectProject(root) {
+  const evidence = { npmPackages: {}, composerPackages: {} };
+  const pkgPath = join(root, 'package.json');
+  if (existsSync(pkgPath)) {
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    Object.assign(evidence.npmPackages, pkg.dependencies ?? {}, pkg.devDependencies ?? {});
+    evidence.npmScripts = pkg.scripts;
+  }
+  const composerPath = join(root, 'composer.json');
+  if (existsSync(composerPath)) {
+    const composer = JSON.parse(readFileSync(composerPath, 'utf8'));
+    Object.assign(evidence.composerPackages, composer.require ?? {}, composer['require-dev'] ?? {});
+  }
+  evidence.hasCodeceptionConfig = existsSync(join(root, 'codeception.yml'));
+  evidence.hasKarmaConfig = ['karma.conf.js', 'karma.conf.ts'].some(name => existsSync(join(root, name)));
+  evidence.hasAngularProject = existsSync(join(root, 'angular.json'))
+    || Boolean(evidence.npmPackages['@angular/core']);
+  return detectTestingAdapter(evidence);
+}
+
+export function detectTestingAdapter(evidence) {
+  const codeceptionVersion = evidence?.composerPackages?.['codeception/codeception'];
+  if (codeceptionVersion) {
+    const major = packageMajor(codeceptionVersion);
+    const known = major === 4 || major === 5;
+    const profile = { runner: 'codeception', version: codeceptionVersion };
+    if (evidence.hasCodeceptionConfig !== undefined) {
+      profile.hasConfig = evidence.hasCodeceptionConfig;
+    }
+    if (!known) {
+      profile.unknowns = ['codeception-major'];
+    }
+    return {
+      family: 'codeception',
+      adapter: 'transpose-codeception.md',
+      complete: known,
+      profile,
+    };
+  }
+  const npmPackages = evidence.npmPackages ?? {};
+  if (
+    evidence.hasKarmaConfig &&
+    evidence.hasAngularProject &&
+    npmPackages.karma &&
+    npmPackages['jasmine-core'] &&
+    npmPackages['@angular/core']
+  ) {
+    const profile = {
+      angular: npmPackages['@angular/core'],
+      karma: npmPackages.karma,
+      jasmineCore: npmPackages['jasmine-core'],
+    };
+    if (npmPackages.typescript) {
+      profile.typescript = npmPackages.typescript;
+    }
+    const unknowns = [];
+    if (packageMajor(profile.angular) !== 10 && packageMajor(profile.angular) !== 11) {
+      unknowns.push('angular-major');
+    }
+    if (packageMajor(profile.karma) !== 6) {
+      unknowns.push('karma-major');
+    }
+    if (packageMajor(profile.jasmineCore) !== 3) {
+      unknowns.push('jasmine-major');
+    }
+    if (unknowns.length > 0) {
+      profile.unknowns = unknowns;
+    }
+    return {
+      family: 'karma-jasmine-angular',
+      adapter: 'transpose-karma-jasmine-angular.md',
+      complete: unknowns.length === 0,
+      profile,
+    };
+  }
+  if (npmPackages.vitest) {
+    return {
+      family: 'vitest',
+      adapter: 'transpose-vitest.md',
+      complete: true,
+      profile: { vitest: npmPackages.vitest },
+    };
+  }
+  return {
+    family: 'unknown',
+    adapter: null,
+    complete: false,
+    profile: {},
+  };
+}
+
+function packageMajor(version) {
+  const match = String(version).match(/\d+/);
+  return match ? Number(match[0]) : undefined;
+}

package/skills/engineering/transpose-testing-patterns/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-testing-patterns/references/doubles-data.md

@@ -0,0 +1,45 @@
+# Doubles, data and isolation
+
+Applies TP-03/04/08/09/10/11. First ask whether the real collaborator is cheap,
+deterministic and part of the behavior. If so, a sociable test often preserves more meaning.
+Isolate a concrete boundary or diagnostic problem, not every object in a constructor.
+
+**The principle: the least synthetic collaborator that keeps the test deterministic, fast
+enough and focused on the behavior.** Least synthetic means closest to what runs in
+production - the real object, then a fake with the real contract, then a spy, then a mock with
+expectations. It is a direction, not a ranking to apply mechanically: the three conditions
+decide, and a real collaborator that makes the test slow, flaky or about something else loses
+to a double. Automatic mocking of every constructor argument answers none of the three
+conditions and replaces the forces with a habit. Nothing here overrides the axes: the level, the
+seam, the double and the data are separate decisions, and a test pyramid is not one of them.
+
+| Need | Candidate | Cost or alternative |
+| --- | --- | --- |
+| Controlled input | Stub function or typed literal | Never stub the policy being claimed as tested |
+| Observable boundary effect | Spy, typed `vi.fn` or message journal | Assert content; count/order only when contractual |
+| Stateful boundary behavior | Fake | Run applicable contracts on the actual adapter; disclose fidelity limits |
+| Required collaboration protocol | Mock expectations | Internal call sequences can make refactors expensive |
+| Simple fresh valid input | Inline data or factory | Defaults must not conceal the decisive value |
+| Named reusable business case | Object mother using a factory | Avoid combinatorial catalogs and shared mutable objects |
+| Meaningful construction/history | Builder using legitimate operations | No two-argument threshold or forced fluent API |
+| Resource lifetime | Fixture/context or hook | Explicit owner, scope and cleanup, including failure |
+
+`vi.fn` can act as stub or spy; its syntax does not make it a strict mock. Compare typed
+functions, object literals and classes for clarity. `satisfies` checks a double without
+widening its useful inferred shape. Do not coerce a partial object into a full dependency
+with `as unknown as`. A narrow production port must express a genuine consumer contract.
+
+Expose controls needed by the scenario, including an adjustable clock. Assert through
+public observations. Builders must not seed private fields or bypass aggregate invariants.
+Helper tests are appropriate when helpers have meaningful behavior, but they do not
+qualify product policy. A fake cannot be the sole implementation of an untested business rule.
+
+Shared contract checks name the guarantee and execute the same applicable scenarios on
+fake and real adapter with fresh resources. File persistence is real infrastructure for a
+file port; a second in-memory implementation is not. Persistence, concurrency, transactions,
+errors and provider semantics need separate evidence when claimed. Do not require a
+contract with an implementation that does not exist.
+
+Testing can reveal the need to control an effect. Reuse an existing seam first. Ask the
+design dimension to decide an architectural extraction only when the force warrants it;
+do not add a test-only public getter or a full hexagonal architecture by default.

package/skills/engineering/transpose-testing-patterns/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-testing-patterns/references/journal-event.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/skills/engineering/transpose-testing-patterns/references/journal-event.schema.json",
+  "title": "Testing patterns journal event 1.0.0",
+  "description": "One event of the append-only journal, filed through `evidence append --kind journal-event`. The event says what was run and what happened; the artifact hashes that make it provable are stamped by the gate, by role, and are not writable here. A replay is marked by the gate, never by the builder.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "record",
+    "scenario",
+    "phase",
+    "command",
+    "exitCode",
+    "output"
+  ],
+  "properties": {
+    "record": {
+      "description": "The decision record this cycle belongs to.",
+      "type": "string",
+      "minLength": 1
+    },
+    "scenario": {
+      "description": "The scenario identifier the record's sites map to.",
+      "type": "string",
+      "minLength": 1
+    },
+    "phase": {
+      "enum": [
+        "red",
+        "green",
+        "refactor"
+      ]
+    },
+    "command": {
+      "description": "The command as run, so it can be run again.",
+      "type": "string",
+      "minLength": 1
+    },
+    "exitCode": {
+      "type": "integer"
+    },
+    "cause": {
+      "description": "What the run reported, quoted from the tool. Required on a red event.",
+      "type": "string",
+      "minLength": 1
+    },
+    "failureClass": {
+      "description": "Required on a red event. `expected-behavior-missing` is the only class a TDD cycle's red is made of: the behavior is absent. `assertion-mismatch` says the behavior exists and disagrees. `setup-error` is setup work, not red.",
+      "enum": [
+        "expected-behavior-missing",
+        "assertion-mismatch",
+        "setup-error"
+      ]
+    },
+    "output": {
+      "description": "The captured output of the actual tool, as a path under the task's evidence or in the worktree.",
+      "type": "string",
+      "minLength": 1
+    },
+    "state": {
+      "description": "An inspectable snapshot or a resolvable immutable ref for this phase.",
+      "type": "string",
+      "minLength": 1
+    },
+    "tests": {
+      "description": "Executed test identities for this scenario, so a claim of coverage maps to real tests.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "skipped": {
+      "description": "Skips, todos, expected failures and retries observed in this run.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "phase": {
+            "const": "red"
+          }
+        },
+        "required": [
+          "phase"
+        ]
+      },
+      "then": {
+        "required": [
+          "cause",
+          "failureClass"
+        ],
+        "properties": {
+          "cause": {
+            "type": "string",
+            "minLength": 1
+          },
+          "failureClass": {
+            "enum": [
+              "expected-behavior-missing",
+              "assertion-mismatch",
+              "setup-error"
+            ]
+          }
+        }
+      }
+    }
+  ]
+}

package/skills/engineering/transpose-testing-patterns/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"
+    }
+  }
+}