@hellraisercenobit/ai-engineering-gate 0.8.0

package/README.md

@@ -0,0 +1,82 @@
+# ai-engineering-gate
+
+Command and enforcement reference. Strategy, workflow diagrams and environment choices (local harness, [no-mistakes](https://kunchenguid.github.io/no-mistakes/), direct PR + CI) live in the [README](../README.md#how-the-suite-works).
+
+One CLI, one JSON surface, three fingerprints. The gate does not judge design, TypeScript or tests: it stores the documents, derives the state, and answers whether a task is complete.
+
+Install it with the Claude Code plugin, with `npm i -g @hellraisercenobit/ai-engineering-gate`, or run it from this checkout:
+
+```sh
+node packages/ai-engineering-gate/dist/ai-engineering-gate.mjs --help
+```
+
+## Opt-in
+
+The gate is silent and allows everything in a repository that does not carry `.ai-engineering-suite.json` at the root. That marker is the project's opt-in. A typical marker:
+
+```json
+{
+  "markerVersion": "1.0.0",
+  "dimensions": "all",
+  "base": "origin/main",
+  "exportDirectory": ".engineering-suite"
+}
+```
+
+`dimensions` may also name a subset of the registry in `contracts/members.json`. Without a registered member the gate fails loud rather than inventing a dimension.
+
+## What it answers
+
+| Command | Question |
+| --- | --- |
+| `status` | compact state of every registered dimension, plus the next action |
+| `declare --dimension D --stdin` | file the applicability decision before any record |
+| `record --dimension D --stdin` | file a decision record; a dangling citation is refused |
+| `evidence append --dimension D --stdin` | append a journal event, a check output or a snapshot |
+| `begin --dimension D` | open a review window and freeze the three fingerprints |
+| `attest` / `report --dimension D --stdin` | file a SOUND envelope, or a SMELLS / VIOLATIONS one |
+| `dispute` / `arbitrate --dimension D --stdin` | contest a finding; only a human-typed command writes an arbitration |
+| `replay --dimension D --record R --scenario S --command C` | the gate runs the red/green pair and stamps both events |
+| `can-write --path P` | may this path be edited now |
+| `can-review --dimension D` | may a fresh review of this dimension start now |
+| `can-stop` | is the task complete; the exit code is the publication lock |
+| `export` | copy the task's documents into the marker's export directory |
+| `fingerprint` | the three fingerprints, as the gate computes them |
+
+`--json` is the schema-checked machine surface. `--full` discloses reasons, missing evidence and the dispatch plan. `--hook` answers in the harness event's own shape.
+
+Exit codes: `0` allowed or valid, `2` denied by policy, `1` gate or infrastructure failure.
+
+```mermaid
+flowchart LR
+  declare --> record --> evidence
+  record --> canWrite["can-write"]
+  evidence --> begin
+  begin --> attest["attest / report"]
+  attest --> canStop["can-stop"]
+  canStop --> export["export, then CI --from-export"]
+```
+
+Publication lock is `can-stop` exit 0. With no-mistakes the driver consumes `can-stop --full` after lint. Without it, CI consumes `can-stop --json --from-export`. Local hooks are advisory. See [how it fits the environment](../README.md#how-it-fits-the-environment).
+
+## Fingerprints
+
+A verdict binds to three content hashes the gate computes and never accepts from a document:
+
+- **source** - declared scope, configuration files and the change set (tracked, staged, untracked)
+- **reference** - the dimension's catalog, schemas and guides plus the contract and gate versions
+- **decision** - the declaration and every record, each with its revision number
+
+A content-neutral rebase leaves a verdict current. A catalog edit, a record revision or a new file in scope expires it.
+
+## Hooks
+
+The plugin ships the three required hooks (`SessionStart`, `PreToolUse`, `Stop`) and the two optional ones (`PostToolUse` eager fingerprint refresh, `SubagentStop` `release --hook`) against this bundle. `SessionStart` and `Stop` inject the **compact** status (`next:` plus `status --full`). The dispatch briefs stay behind an explicit `can-stop --full` / `status --full`, which is what a no-mistakes driver runs. Neither optional hook decides validity. `npm run install:hooks -- --optional` covers a skills.sh install and Codex. Codex has no `sessionStart` context injection; the installer reports that limit instead of wiring a hook that answers into the void.
+
+## Threat model
+
+The gate catches omission, drift and stale evidence. It does not defend against a forged index or a write through a tool the hooks do not see. `can-write` denies harness edits and shell write forms that target the index outside gate commands.
+
+## AXI
+
+The surface is self-assessed against a pinned AXI text in `contracts/axi/`. `npm run check:axi` re-runs the named assertions. There is no AXI runtime dependency, and a new upstream revision requires a re-qualification, never a silent bump.

package/agents/design-pattern-reviewer.md

@@ -0,0 +1,40 @@
+---
+name: design-pattern-reviewer
+description: Fresh, read-only reviewer for design-pattern audits. Runs the review-design-patterns skill on code it did not write - blind matrix first, then the recorded decision, then the code - and attests only a SOUND verdict. Use after a transpose-design-patterns implementation, with the brief that skill prescribes.
+tools: Read, Grep, Glob, Bash, Skill
+model: inherit
+---
+
+# Design-pattern reviewer
+
+You are the independent reviewer for one change. You did not write the code, you have no stake in it,
+and your output is judgment only.
+
+## Protocol
+
+Open your window first with `ai-engineering-gate begin --dimension design-patterns`: it prints the three
+fingerprints your verdict will bind to and refuses you if you are the builder of this task. Then invoke the
+`review-design-patterns` skill (the Skill tool; reading its `SKILL.md` loads the same text) and run every
+step yourself on the scope the brief gives you. Do not dispatch another reviewer: you are the fresh one.
+File the review envelope through `ai-engineering-gate attest --dimension design-patterns --stdin` for
+`SOUND`, or `ai-engineering-gate report --dimension design-patterns --stdin` otherwise.
+
+## Rules that do not bend
+
+- **The catalog is the standard.** The author's pattern names, comments, commit messages and rationale are
+  never evidence.
+- **Freeze before you compare.** Write your expected design for every site before you open the design
+  decision record named in the brief. Open it only when the skill's step 4 says to.
+- **Never modify a file.** Bash is read-only here: `git diff`, search, `cat`, and the gate commands that
+  open the window and file the envelope. Never `git log`: commit subjects carry the author's intent. A fix
+  belongs to the author, followed by a fresh review.
+- **Attest only `SOUND`.** `SMELLS` and `VIOLATIONS` are filed through `report`, never attested. Both need
+  the window you opened; a refusal of `state-moved` means the code changed while you read it, so the review
+  is void - say so and stop rather than filing on code you did not read.
+- **A brief that carries a pattern name, a rationale or the author's force analysis is contaminated.** The
+  requirement as the requester stated it is legitimate context. Say so in the report and derive anyway -
+  the frozen matrix still comes first.
+
+## Output
+
+The skill's report format, ending on one verdict. Nothing else.

package/agents/modern-typescript-reviewer.md

@@ -0,0 +1,24 @@
+---
+name: modern-typescript-reviewer
+description: Fresh read-only reviewer for TS/JS decisions. Runs review-modern-typescript without builder history, freezes expectations before records, and attests only SOUND.
+tools: Read, Grep, Glob, Bash, Skill
+model: inherit
+---
+
+# Modern TypeScript reviewer
+
+Open your window with `ai-engineering-gate begin --dimension modern-typescript`, which prints the
+three fingerprints your verdict binds to and refuses you if you built this task. Then run
+/review-modern-typescript yourself on the neutral brief's exact scope. Read its skill file if no
+Skill tool exists. You own no additional rules and do not delegate.
+
+Modify no files, including code, records, catalogs and fixtures. Shell access is read-only; the
+sole external mutation is the review envelope, piped to
+`ai-engineering-gate attest --dimension modern-typescript --stdin` for SOUND or to
+`ai-engineering-gate report --dimension modern-typescript --stdin` otherwise. Put no fingerprint
+in it. A refusal of `state-moved` voids the review: say so and stop. Never git log or PR
+rationale. Check record paths exist but open contents only after emitting the frozen matrix.
+
+A brief with builder choices or rationale needs a new neutral dispatch before completion.
+The original user request and independent constraints are legitimate facts. Return the
+skill report. The builder fixes and dispatches a new reviewer.

package/agents/testing-pattern-reviewer.md

@@ -0,0 +1,23 @@
+---
+name: testing-pattern-reviewer
+description: Fresh read-only reviewer for testing decisions and TDD evidence. Runs review-testing-patterns, freezes expectations before records and attests only SOUND.
+tools: Read, Grep, Glob, Bash, Skill
+model: inherit
+---
+
+# Testing pattern reviewer
+
+Open your window with `ai-engineering-gate begin --dimension testing-patterns`, which prints the
+three fingerprints your verdict binds to and refuses you if you built this task. Then run
+/review-testing-patterns yourself on the neutral brief's exact scope. Read the skill file if no
+Skill tool exists. You own no additional rules and do not delegate.
+
+Modify no files, including fixtures and evidence. Shell access is read-only; the sole external
+mutation is the review envelope, piped to
+`ai-engineering-gate attest --dimension testing-patterns --stdin` for SOUND or to
+`ai-engineering-gate report --dimension testing-patterns --stdin` otherwise. Never run a test to
+produce evidence for the builder: a missing red is an evidence finding whose remedy is a `replay`
+the gate performs. A refusal of `state-moved` voids the review: say so and stop. Never read git
+log or PR rationale. Check record paths exist, then freeze the matrix before opening their
+contents. Return the skill report. The builder corrects or disputes, then a fresh reviewer
+reassesses.

package/bin/ai-engineering-gate.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// The generated bundle is what ships and what the hooks run, so the executable runs it too rather than
+// the sources beside it: a stale bundle then fails the tests, not only the check.
+import { main } from '../dist/ai-engineering-gate.mjs';
+
+process.exitCode = main(process.argv.slice(2));

package/contracts/axi/axi-standard.md

@@ -0,0 +1,273 @@
+---
+name: axi
+description: >
+  Agent eXperience Interface (AXI) — ergonomic standards for building CLI tools that agents
+  use via shell execution. Use when building, modifying, or reviewing any agent-facing CLI.
+---
+
+# Agent eXperience Interface (AXI)
+
+AXI defines ergonomic standards for building CLI tools that autonomous agents interact with through shell execution.
+
+## Before you start
+
+Read the [TOON specification](https://toonformat.dev/reference/spec.html) before building any AXI output.
+
+## 1. Token-efficient output
+
+Use [TOON](https://toonformat.dev/) (Token-Oriented Object Notation) as the output format on stdout.
+TOON provides ~40% token savings over equivalent JSON while remaining readable by agents.
+Convert to TOON at the output boundary — keep internal logic on JSON.
+
+```
+tasks[2]{id,title,status,assignee}:
+  "1",Fix auth bug,open,alice
+  "2",Add pagination,closed,bob
+```
+
+## 2. Minimal default schemas
+
+Every field in stdout costs tokens — multiplied by row count in collections.
+Default to the smallest schema that lets the agent decide what to do next: typically an identifier, a title, and a status.
+
+- Default list schemas: 3-4 fields, not 10
+- Default limits: high enough to cover common cases in one call (if most repos have <100 labels, default to 100, not 30)
+- Long-form content (bodies, descriptions) belongs in detail views, not lists
+- Offer a `--fields` flag to let agents request additional fields explicitly
+
+## 3. Content truncation
+
+Detail views often contain large text fields. Omitting them forces agents to hunt; including them wastes tokens.
+Truncate by default and tell the agent how to get the full version.
+
+```
+task:
+  number: 42
+  title: Fix auth bug
+  state: open
+  body: First 500 chars of the issue body...
+    ... (truncated, 8432 chars total)
+help[1]: Run `tasks view 42 --full` to see complete body
+```
+
+- Never omit large fields entirely — include a truncated preview
+- Show the total size so the agent knows how much it's missing
+- Suggest the escape hatch (`--full`) only when content is actually truncated
+- Choose a truncation limit that covers most use cases (500-1500 chars)
+
+## 4. Pre-computed aggregates
+
+The most expensive token cost is often not a longer response — it's a follow-up call. If your backend has data that agents commonly need as a next step, compute it and include it.
+
+**Aggregate counts**: include the **total count** in list output, not just the page size. Agents need "how many are there?" and will paginate if the answer isn't definitive.
+
+```
+count: 30 of 847 total
+tasks[30]{number,title,state}:
+  1,Fix auth bug,open
+  ...
+```
+
+**Derived status fields**: when the next step almost always involves checking related state, include a lightweight summary inline.
+
+```
+task:
+  number: 42
+  title: Deploy pipeline fix
+  state: open
+  checks: 3/3 passed
+  comments: 7
+```
+
+Only include derived fields your backend can provide cheaply — a summary ("3/3 passed"), not the full data.
+
+## 5. Definitive empty states
+
+When the answer is "nothing", say so explicitly. Ambiguous empty output causes agents to re-run with different flags to verify.
+
+```
+$ tasks list --state closed
+tasks: 0 closed tasks found in this repository
+```
+
+State the zero with context. Make it clear the command succeeded — the absence of results is the answer.
+
+## 6. Structured errors & exit codes
+
+### Idempotent mutations
+
+Don't error when the desired state already exists. If the agent closes something already closed, acknowledge and move on with exit code 0. Reserve non-zero exit codes for situations where the agent's intent genuinely cannot be satisfied.
+
+```
+$ tasks close 42
+task: #42 already closed (no-op)    # exit 0
+```
+
+### Structured errors on stdout
+
+Errors go to **stdout** in the same structured format as normal output, so the agent can read and act on them. Include what went wrong and an actionable suggestion. Never let raw dependency output (API errors, stack traces) leak through.
+
+```
+error: --title is required
+help: tasks create --title "..." [--body "..."]
+```
+
+- Validate required flags before calling any dependency
+- Translate errors — extract actionable meaning, discard noise
+- Never leak dependency names — suggestions reference your CLI's commands, not the underlying tool
+
+### No interactive prompts
+
+Every operation must be completable with flags alone. If a required value is missing, fail immediately with a clear error — don't prompt for it. Suppress prompts from wrapped tools.
+
+### Fail loud on unrecognized input
+
+Reject unknown flags and arguments — never silently ignore them. A dropped flag is worse than an error: the agent gets plausible-looking output it believes is scoped or filtered, then proceeds confidently on wrong data. This is the same guarantee a CLI already owes for an unknown _command_; extend it to flags.
+
+```
+$ tasks list --stat closed
+error: unknown flag --stat for `list`
+help: valid flags for `list`: --state, --assignee, --limit (--help always allowed)
+```
+
+- **Validate before any dependency call**, with exit code 2 — the same as a missing required flag. Each command declares its own known flags; an unrecognized one is rejected by name and the command's valid flags are listed.
+- **`--help` always passes** — it's the one universal flag. Beyond it, a CLI may standardize its own always-allowed globals (e.g. an `--account` selector); whatever the set, those flags pass on every command and are never reported as unknown.
+- **Renamed or removed flags get a targeted hint**, not the generic list — point at what replaced them (`--status was renamed; use --state instead`) so the agent self-corrects in one step.
+- **Per-subcommand flag sets.** For grouped nouns where one command dispatches to subcommands (a `list` vs a `create` under the same noun), validate against the _subcommand's_ flags — they differ, and only the subcommand layer knows which is in play.
+- **Make the error self-correcting in one turn.** The agent's deterministic next move after an unknown-flag error is to run `<command> --help` (e.g. `tasks list --help`) — so fold that lookup into the error: list the valid flags inline, or print the command's concise `--help` block directly beneath it. Per §4 the expensive cost is the follow-up call, and per §10 per-command help is already concise, so inlining it collapses the two-turn correction into one.
+
+### Output channels
+
+- **stdout**: all structured output the agent consumes — data, errors, suggestions
+- **stderr**: debug logging, progress indicators, diagnostics (agents don't read this)
+- **Exit codes**: 0 = success (including no-ops), 1 = error, 2 = usage error
+
+Never mix progress messages into stdout. An agent that reads "Fetching data..." will try to interpret it as data.
+
+## 7. Ambient context via session integrations
+
+Register your tool into the agent's session lifecycle so every conversation starts with relevant state already visible — before the agent takes any action.
+
+**Pattern:**
+
+1. Provide an explicit setup command that installs or repairs a session hook or plugin after user intent is clear
+2. At session start, the integration runs your tool and provides a compact dashboard as context
+3. The agent receives this as initial context and can act immediately
+
+```
+# Agent sees this at session start — no invocation needed:
+specs[2]{id,title,status}:
+  1,Fix auth bug,open
+  2,Add pagination,in-progress
+
+help[2]:
+  Run `mytool specs view 1` for details
+  Run `mytool specs create --title "..."` to add a spec
+```
+
+**Rules:**
+
+- **Default app targets**: by default, support Claude Code, Codex, and OpenCode. Do not hard-code a single agent integration when the tool can reasonably support multiple agents
+- **Explicit opt-in**: register hooks or plugins only from a user-invoked setup command, not from ordinary CLI commands
+- **Portable commands**: hook commands should use a PATH-verified binary name when it resolves to the current executable, and fall back to the full absolute path otherwise. This keeps global installs portable while ensuring hooks do not accidentally run a different binary
+- **Path repair**: setup commands should check existing hooks and update the executable path if it has changed (e.g., after reinstall or relocation)
+- **Idempotent**: repeated installs with the same path are silent no-ops
+- **Directory-scoped**: show only state relevant to the current working directory
+- **Token-budget-aware**: this context loads on _every_ session — ruthlessly minimize it. Include just enough for the agent to orient and act; deep data belongs in explicit invocations
+- **Lifecycle capture**: use session-end hooks to capture what happened (transcripts, files touched, specs referenced) so future session-start context gets richer over time
+
+**How to integrate with each app:**
+
+- **Claude Code**: use native hooks in `~/.claude/settings.json` or project `.claude/settings.json`. Prefer `SessionStart` to inject compact context via stdout
+- **Codex**: use native hooks in `~/.codex/hooks.json` or `<repo>/.codex/hooks.json`, and ensure `[features].hooks = true` in `config.toml`. Prefer `SessionStart` for ambient context via stdout
+- **OpenCode**: use a managed plugin in `~/.config/opencode/plugins/` or `<repo>/.opencode/plugins/`. Prefer ambient system-context injection for the home view rather than adding a custom tool
+
+**Also ship an installable skill (secondary recommendation):**
+
+The session hook is the primary integration, but it only helps agents whose harness supports hooks, and it loads on _every_ session.
+Offer an installable [Agent Skill](https://agentskills.io) as a secondary discovery path.
+It loads on demand when the agent recognizes a matching task, carries no per-session token cost, and works in any agent that supports the skill format.
+Recommend the hook first (ambient context plus live state) and the skill second (lower overhead, broader agent support) - they are complementary, and a user installs whichever fits, or both.
+
+```sh
+npx skills add <owner>/<repo> --skill <name>
+```
+
+- **Single source of truth**: generate `SKILL.md` from the same content your no-args home view prints, so the skill never drifts from the CLI's own guidance. Add a `--check` build step to CI that fails if the committed skill is stale
+- **Strip live state**: a skill is static, so omit dynamic data (open sessions, current items) that only the hook can show
+- **Non-interactive commands**: rewrite command examples to a form the agent can run without a global install (e.g. `npx -y mytool ...`), since a skill may be installed without the binary on PATH
+- **Trigger-shaped frontmatter**: include `name` and a `description` written as a trigger — terse and outcome-focused so the agent loads it on the right intent
+- **Document both paths**: in your README, present the hook and the skill as two ways to achieve the same thing, and make clear the user only needs one
+
+## 8. Content first
+
+Running your CLI with no arguments should show the most relevant live content — not a usage manual.
+When an agent sees actual state it can act immediately. When it sees help text, it has to make a second call.
+
+```
+$ tasks
+tasks[3]{id,title,status}:
+  1,Fix auth bug,open
+  2,Add pagination,open
+  3,Update docs,closed
+help[2]:
+  Run `tasks view <id>` to see full details
+  Run `tasks create --title "..."` to add a task
+```
+
+## 9. Contextual disclosure
+
+Include **a few next steps** that follow logically from the current output.
+The agent discovers your CLI's surface area organically by using it, not by reading a manual upfront.
+
+Rules:
+
+- **Relevant**: after an open item → suggest closing; after an empty list → suggest creating; after a list → suggest viewing
+- **Actionable**: every suggestion is a complete command (or template) carrying forward any disambiguating flags from the current invocation (e.g., `--repo`, `--source`)
+- **Parameterize dynamic values**: when a suggested command needs a runtime value such as an ID, title, branch, URL, or path, use placeholders like `<id>` or `"<title>"` instead of guessing a concrete value that may mislead the agent
+- **Omit when self-contained**: when the output fully answers the query (a detail view, a count, a confirmation), suggestions are noise — leave them out. Include them on list and mutation responses where the next step isn't obvious.
+- **Guide discovery, not workflows**: suggest a variety of possible next actions, don't prescribe a fixed sequence. An agent that already knows what it wants should never be nudged into an extra step.
+- **Reveal truncated lists**: when a list shows only the most recent N items out of a larger total, add a help hint telling the agent how to see all of them (e.g., `Run 'mytool list' for all 47 items`). Don't encode pagination into TOON array headers — use help hints instead.
+- **Resolve errors**: on errors, suggest the specific command that fixes the problem, not "see `--help`"
+
+## 10. Consistent way to get help
+
+The top-level home view should also identify the tool itself before the live data:
+
+- Include the absolute path of the current executable, with the user's home directory collapsed to `~`
+- Include a one-sentence description of what this AXI does
+
+```
+$ tasks
+bin: ~/.local/bin/tasks
+description: Manage project tasks in the current workspace
+...
+```
+
+Every subcommand should support `--help` with a concise, complete reference: available flags with defaults, required arguments, and 2-3 usage examples. Keep it focused on the requested subcommand — don't dump the entire CLI's manual.
+
+### Identify yourself instantly: the `--version` fast path
+
+`-v`, `-V`, and `--version` must all print the bare version and exit 0. Agents and their harnesses probe `--version` constantly - to confirm a tool is installed, to check whether a fix has shipped, to decide whether to suggest `update`. That makes latency an ergonomics property, not just a perf tweak: a probe that takes 80 ms is 80 ms of every session start, paid before any useful work happens.
+
+The trap is ESM static imports. If `bin/<tool>.js` statically imports the module that builds the command graph, every dependency in that graph is fully evaluated _before_ the version check runs. One heavy import anywhere in the tree - an SDK, a server framework - is then paid on every `--version`.
+
+Answer the version before the graph loads: keep the version in a leaf module that imports only node builtins, and defer the real CLI to a dynamic `import()`.
+
+```js
+#!/usr/bin/env node
+import { tryFastPath } from "axi-sdk-js/fast-path";
+import { VERSION } from "../src/version.js"; // leaf module - node builtins only
+
+if (!tryFastPath(process.argv.slice(2), { version: VERSION })) {
+  const { main } = await import("../src/cli.js"); // heavy graph loads only here
+  await main();
+}
+```
+
+`axi-sdk-js/fast-path` is a dedicated subpath export that imports nothing at all, so pulling it in never drags in `runAxiCli` or its dependencies. `tryFastPath` handles only a bare, single-argument version flag and returns `false` for everything else, so all other argv - including version flags in trailing positions - falls through to `runAxiCli`, which stays the single owner of the general case. Its accepted flags and output are identical to the SDK's own version handling, so adopting it changes nothing an agent can observe except the latency.
+
+Two things keep this honest:
+
+- The version must come from a **leaf** module. If `VERSION` is defined inside `cli.ts`, importing it re-pulls the whole graph and the fast path buys nothing.
+- Guard it with a test that measures the version path against the `node -e "console.log(1)"` floor measured in the same process, rather than an absolute millisecond budget that goes flaky across machines.

package/contracts/axi/pin.json

@@ -0,0 +1,36 @@
+{
+  "upstream": "https://github.com/kunchenguid/axi",
+  "revision": "b7dbc1324ce637f08835ce5c45783a24287511f2",
+  "path": ".agents/skills/axi/SKILL.md",
+  "text": "contracts/axi/axi-standard.md",
+  "textHash": "sha256:2f5a6b3dd6f84bb3ee56d814ac6dde00c3c2b54fd0b0554129c2680a655948c4",
+  "qualifiedOn": "2026-09-18",
+  "complianceLevel": "partial, self-assessed against the pinned text",
+  "assessment": "This repository asserts the surface properties below against the pinned text by running the gate. It is self-assessment, not an upstream certification, and it carries no AXI runtime dependency. A new upstream revision requires re-qualification: the pin, the text and this assessment move together, or the claim does not move at all.",
+  "adopted": [
+    "2 - minimal default schemas: the compact status is one row per dimension with its state, not its evidence",
+    "3 - content truncation: reasons, missing evidence and the dispatch plan sit behind `--full`",
+    "4 - pre-computed aggregates: the compact status carries the round, the completion codes and the next action, so the caller needs no follow-up to know where the task stands",
+    "5 - definitive empty states: a repository with no marker prints nothing and allows, and a dimension with nothing to do says so",
+    "6 - structured errors and exit codes: 0 allowed, 2 denied by policy, 1 gate failure; a refusal carries its code, its reason and its cause; unknown flags fail loud; no command prompts",
+    "7 - ambient context: the plugin's SessionStart hook injects the compact status, and the installer covers the routes a plugin does not",
+    "8 - content first: no argument prints the live state of the task, never the manual",
+    "9 - contextual disclosure: every answer ends on the next command to run, with placeholders rather than guessed values",
+    "10 - consistent help: `--help` lists every command, flag and exit code in one screen"
+  ],
+  "notAdopted": [
+    "1 - TOON output: the gate's machine surface is JSON validated against `contracts/schemas/gate-output.schema.json`, because the contract pins that surface for reviewers, harness hooks and CI alike, and a second serialization would be a second thing to keep true. The compact surface stays a table plus a `next` line, which is what the suite contract describes."
+  ],
+  "surfaceAssertions": [
+    "no-argument output is live state",
+    "compact status names one state per dimension",
+    "compact status names the next action",
+    "reasons are disclosed only behind --full",
+    "json output is versioned and schema-valid",
+    "an unknown flag fails loud on stderr",
+    "a refusal is structured on stdout",
+    "exit codes are 0, 2 and 1 as documented",
+    "help lists every command and exit code",
+    "an unmarked repository is silent and allows"
+  ]
+}

package/contracts/members.json

@@ -0,0 +1,58 @@
+{
+  "contractVersion": "1.1.0",
+  "members": [
+    {
+      "dimension": "design-patterns",
+      "transpose": "skills/engineering/transpose-design-patterns",
+      "review": "skills/engineering/review-design-patterns",
+      "agent": "agents/design-pattern-reviewer.md",
+      "decisionSchema": "skills/engineering/transpose-design-patterns/references/design-decision-record.schema.json",
+      "evidenceSchemas": {},
+      "referenceBundle": [
+        "skills/engineering/transpose-design-patterns/references",
+        "skills/engineering/review-design-patterns/references"
+      ],
+      "contractVersions": [
+        "1.0.0",
+        "1.1.0"
+      ],
+      "status": "implemented"
+    },
+    {
+      "dimension": "modern-typescript",
+      "transpose": "skills/engineering/transpose-modern-typescript",
+      "review": "skills/engineering/review-modern-typescript",
+      "agent": "agents/modern-typescript-reviewer.md",
+      "decisionSchema": "skills/engineering/transpose-modern-typescript/references/decision-record.schema.json",
+      "evidenceSchemas": {},
+      "referenceBundle": [
+        "skills/engineering/transpose-modern-typescript/references",
+        "skills/engineering/review-modern-typescript/references"
+      ],
+      "contractVersions": [
+        "1.0.0",
+        "1.1.0"
+      ],
+      "status": "implemented"
+    },
+    {
+      "dimension": "testing-patterns",
+      "transpose": "skills/engineering/transpose-testing-patterns",
+      "review": "skills/engineering/review-testing-patterns",
+      "agent": "agents/testing-pattern-reviewer.md",
+      "decisionSchema": "skills/engineering/transpose-testing-patterns/references/decision-record.schema.json",
+      "evidenceSchemas": {
+        "journal-event": "skills/engineering/transpose-testing-patterns/references/journal-event.schema.json"
+      },
+      "referenceBundle": [
+        "skills/engineering/transpose-testing-patterns/references",
+        "skills/engineering/review-testing-patterns/references"
+      ],
+      "contractVersions": [
+        "1.0.0",
+        "1.1.0"
+      ],
+      "status": "implemented"
+    }
+  ]
+}

package/contracts/schemas/arbitration.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/hellraisercenobit/skills/blob/main/contracts/schemas/arbitration.schema.json",
+  "title": "Arbitration 1.0.0",
+  "description": "A dispute's only exit, and only a human hand writes it. `arbitrate` is refused whenever an identity handoff exists for the call, which is the case for every agent tool call a hook saw.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "document",
+    "documentVersion",
+    "dimension",
+    "dispute",
+    "decision",
+    "words"
+  ],
+  "properties": {
+    "document": {
+      "const": "arbitration"
+    },
+    "documentVersion": {
+      "const": "1.0.0"
+    },
+    "dimension": {
+      "type": "string",
+      "minLength": 1
+    },
+    "dispute": {
+      "description": "The identifier of the dispute being arbitrated.",
+      "type": "string",
+      "minLength": 1
+    },
+    "decision": {
+      "description": "`uphold` closes the finding by arbitration and allows one fresh review on the same state; `reject` puts its remedy or correction back to pending.",
+      "enum": [
+        "uphold",
+        "reject"
+      ]
+    },
+    "words": {
+      "description": "The user's own words.",
+      "type": "string",
+      "minLength": 1
+    }
+  }
+}