@hellraisercenobit/ai-engineering-gate 0.8.0

package/contracts/suite-contract.md

@@ -0,0 +1,270 @@
+# Transpose/review contract 1.1.0
+
+Canonical source: `contracts/suite-contract.md` in hellraisercenobit/skills. Copies in
+transpose bundles are generated by `npm run sync:contract`; never edit them by hand.
+The repository maintainer owns this contract. Domain catalogs and record schemas remain
+owned by their transpose skill. Read this contract once per execution.
+
+1.1.0 adds clauses to 1.0.0 and changes none of its guarantees. Each member declares the
+contract versions it supports in the member manifest. A workflow that runs on records,
+checks and independent reports without any gate stays valid under 1.1.0: the clauses below
+describe what enforcement derives, never a new obligation on prose.
+
+## Guarantees
+
+| ID | Requirement | Evidence |
+| --- | --- | --- |
+| C01 | One normative catalog per dimension, owned by transpose and read by review. | Resolved local references and identified versions or content hashes. |
+| C02 | Explicit scope and comparison base. | Files and sites, including relevant uncommitted and untracked files. |
+| C03 | Inventory every relevant site, including retained choices. | Domain criteria, alternatives and observable invariants. |
+| C04 | Record each decision before the first affected implementation write. | Schema-valid records outside the repository; preserve previous revisions and reasons. |
+| C05 | Separate deterministic checks from semantic judgment. | Schema/catalog membership and applicable type, runtime, lint and build checks. |
+| C06 | Independent reviewer with a neutral brief. | Fresh context without builder history or rationale; original request and factual constraints only. |
+| C07 | Freeze expectations before reading records or author justification. | Immutable expected matrix in the review transcript; no `git log`, PR rationale or author analysis. |
+| C08 | Compare every site; steelman every candidate finding. | Expected/recorded/actual, exact rule, evidence, strongest defense and refutation. |
+| C09 | Reviewer changes no files and delegates no review. | Report in its response; the builder fixes and dispatches a new fresh reviewer. |
+| C10 | Only a current `SOUND` completes transposition. | Complete audit, zero confirmed findings, passing applicable checks and no unresolved dispute. |
+| C11 | Only the reviewer attests; scope changes invalidate its verdict. | Examined state identified; the gate computes the fingerprints a verdict binds to. |
+| C12 | Missing prerequisites and limits are explicit. | No invented rules, support, independence or attestation. |
+
+## Shared execution rules
+
+Resolve companions, schema, catalog, this contract and any **required** guides first. Pin
+their versions or hashes for the execution. A missing optional guide is acceptable only
+when the domain permits catalog-only decisions. Conflicting installed contract/catalog
+versions are an incomplete prerequisite; do not silently download another version.
+
+The builder inventories scope, compares alternatives including the current implementation,
+records, then writes and checks. Coherent local choices can share a record if every site
+remains identifiable. `none` has the domain's explicit meaning; it is not a shortcut around
+evaluation. No applicable site is a justified non-applicable dimension, not an artificial
+`SOUND`. Do not add common fields to a domain schema that forbids them: coordination
+metadata belongs in an external execution index.
+
+The reviewer reads independent requirements and factual constraints, inventories the scope
+and freezes a matrix of expected acceptable choices, rules and invariants **in its response
+before the next tool call that opens records**. It then compares expected, recorded and
+actual. Record absence is not a retrospective code defect in a standalone audit; a claimed
+completed transposition requires its records. State significant exposure to author
+justification. A contaminated brief requires a new reviewer before completion; do not
+rewrite the frozen matrix to match the builder. Verified new facts that change premises
+require a new framing and fresh review, retaining the old matrix.
+
+For each candidate, construct the strongest defense (compatibility, public contract, domain
+meaning, framework semantics, proven cost or legitimate simplicity). Drop it if that defense
+holds. Confirm only with an applicable catalog rule and evidence. Report catalog gaps
+separately, without severity or verdict impact. A gap is not permission to invent a rule.
+
+Reports identify scope/base/state, reference versions, coverage, frozen matrix, comparison,
+confirmed findings, defended choices, gaps and check evidence. Each finding identifies
+location, rule, expected/recorded/actual, impact, defense, refutation and proposed correction.
+Severity: `Blocker` for concrete correctness/support failures, `Major` for demonstrated
+structural costs or missing guarantees, `Minor` for evidenced idiomatic drift after defense.
+Age or taste alone is never evidence. This clause owns the severity tiers; a domain skill
+references it instead of restating them.
+
+| Verdict | Meaning |
+| --- | --- |
+| SOUND | Complete audit, zero confirmed findings. |
+| SMELLS | Confirmed findings, no Blocker. |
+| VIOLATIONS | At least one Blocker. |
+
+An incomplete execution reports the missing prerequisite and has no attestable quality
+verdict; it is not a fourth verdict. The reviewer edits neither code, records, catalogs nor
+fixtures. Its report is a response that the harness can save externally. Its sole permitted
+external mutations are the gate's attestation and report operations, when supported;
+attestation accepts `SOUND` only. A dispute goes to the user and remains unresolved until
+decided; it is not a fix.
+
+## Dimension registry
+
+The member manifest `contracts/members.json` is the registry. It owns, per member: the
+dimension identifier, the transpose and review skill locations, the reviewer agent, the
+decision schema, the evidence schemas the dimension owns, the reference bundle, the contract
+versions the member supports, and a status, `implemented` or `qualified`. Nothing else
+defines a dimension identifier, and no other file lists the dimensions.
+
+The registry holds orchestration metadata and schema locations only: never a rule, a pattern
+name, an idiom or a test form. Adding a dimension is a registration plus a qualification. It
+never changes enforcement logic and never adds a hook.
+
+## State and evidence
+
+Store evidence, derive state. Every durable fact is a schema-valid document on disk: a
+declaration, a decision record, an evidence append, an attestation, a report, a dispute or
+an arbitration. No implementation persists a workflow boolean such as "reviewed" or
+"fresh"; state is recomputed from those documents and from the code they cover.
+
+A project opts in with one committed marker at its repository root, which also carries the
+project's dimension selection and its evidence and export locations. Without that marker,
+enforcement is silent and every workflow stays portable. Evidence lives outside the
+checkout, under a task key derived from the branch.
+
+### Declaration
+
+Before the first record, a task declares each registered dimension applicable or
+non-applicable, with a reason, the requester's wording of the request and the factual
+constraints. An applicable declaration also names its scope, as repository-relative file
+paths or directory prefixes, and the relevant configuration files. A non-applicable
+dimension has a declaration and nothing else: skipping a dimension is a recorded decision,
+never a default, and an undeclared registered dimension is an incomplete task.
+
+The declaration is what protects the scope and what a neutral brief is rendered from. It is
+revisioned like a record, and it locks once a record, report, review window or dispute
+depends on it, unless the revision only widens scope or adds constraints.
+
+### Fingerprints
+
+"Current" means three fingerprints.
+
+- **Source**: the content hashes of the union of the declared scope paths, the declared
+  configuration files and the change set. The change set is the tracked diff between the
+  merge-base of the recorded base and HEAD, plus staged, unstaged and untracked files, minus
+  the export directory, the gate-owned paths and the marker's ignore patterns. Content
+  hashes only: the base revision is recorded and not hashed, so a content-neutral rebase
+  does not expire a verdict, and a clean HEAD never identifies a dirty worktree. Change-set
+  paths outside every applicable declaration are reported as undeclared changes.
+- **Reference**: the content hashes of the dimension's reference bundle as distributed —
+  catalog, decision schema, evidence schemas, guides, the review skill's references and the
+  generated copy of this contract — plus the contract version and the gate version.
+- **Decision**: the ordered hash of the dimension's declaration and of every decision record
+  of the dimension for the task, each with its revision number.
+
+A verdict is current only while all three fingerprints it was bound to still match. Any
+mismatch is stale. Eager marking by a PostToolUse hook is an optimization and is never
+authoritative: a skipped hook, a crash or an editor outside the harness must never leave a
+stale verdict looking current, so expiry is always derived from the fingerprints.
+
+### Envelopes
+
+Every decision record carries a common outer envelope: dimension, schema version, catalog
+version, the contract versions it supports, need, scope as an array of paths, base, revision
+as number, previous and reason, and two typed lists — `cites`, artifacts and evidence
+sources that exist when the record is validated, and `plans`, artifacts the record commits
+to produce, each with its dimension-defined role. The dimension-specific body stays owned by
+the dimension schema. Applicability is not a record field; it lives in the declaration.
+
+`cites` carries referential integrity. A cited path that does not exist refuses the record.
+A claim of unknown about a checkable fact — targets, runtimes, environments, configuration —
+is accepted only with the sources consulted cited, or with the paths searched and not found.
+A revision that announces a correction is refused when no cited artifact changed: a record
+describes what was done, not what should have been. `plans` are not checked when the record
+is written, so a record that precedes the first affected write stays valid under C04; every
+planned artifact must exist before a review begins, is filed or is dispatched.
+
+Every review emits a common review envelope: dimension, the supported contract version, the
+verdict, the records examined, the checks it saw executed, a reviewer object with an
+independence claim and a declared identity, the confirmed findings and the
+challenged-survived list. Each finding has an identifier and a kind, `evidence` or
+`judgment`; an evidence finding carries a typed remedy, a judgment finding the proposed
+correction C08 already requires. The envelope carries no fingerprint: a fingerprint a
+builder or a reviewer writes anywhere is ignored.
+
+### Attestation and report
+
+The gate writes both, and they are the reviewer's only permitted external mutations. An
+attestation stores a `SOUND` envelope together with the three fingerprints of the reviewer's
+window and its captured identity. A report stores a `SMELLS` or `VIOLATIONS` envelope bound
+the same way; it blocks completion until a `SOUND` attestation on a later state, or an
+arbitration closing its last open finding, supersedes it. No other verdict is attestable and
+no verdict is a score.
+
+### Findings, disputes and arbitration
+
+A finding admits two responses: address it — the remedy executed and the artifact appended,
+or the record revised and the state moved — or dispute it with a pointer to existing
+counter-evidence. An answer in prose is neither, and a changed fingerprint alone addresses
+nothing. Findings about evidence say evidence not on file, never false claim: the builder is
+asked to file, not to confess.
+
+While any finding of the last report is pending, no new review of that dimension begins, so
+the same finding is never re-litigated with a fresh reviewer. A valid dispute blocks
+completion and goes to the user; it never goes to another reviewer on the same state. Its
+only exit is an arbitration that only a human hand writes: `uphold` closes the finding,
+`reject` puts its remedy or correction back to pending.
+
+### Reviewer identity
+
+Every gate call carries the harness session identifier. A reviewer's calls carry an agent
+identifier that must differ from the builder's. This checks consistency, not independence.
+Where a harness provides no agent identifier, the attestation is stored unverified, the state
+says so, and a pipeline may require verified identity.
+
+### Completion
+
+For each registered dimension: a non-applicable declaration needs its reason; an applicable
+one needs at least one validated record, every planned artifact produced, a current `SOUND`
+attestation, no current report with an open finding and no unresolved dispute. An undeclared
+registered dimension is incomplete. Any incomplete dimension blocks completion whatever the
+others say. Requirements combine; they never average, and there is no score.
+
+Deterministic checks stay the reviewer's responsibility under C10 and appear in the review
+envelope as the checks it saw executed. Enforcement validates their presence, never their
+result.
+
+## Neutral brief
+
+Send only the filled fields below to the named reviewer or a fresh general subagent with
+no inherited conversation. Keep test expectations and other reviewers' conclusions out.
+
+```text
+You are the fresh <dimension> reviewer. Run /<review-skill> yourself; do not delegate.
+Read-only: do not modify any file, including code, records, catalogs or fixtures.
+Scope: <exact paths/symbols>; repository: <absolute path>.
+Base: <ref/commit or standalone>; include relevant uncommitted and new files.
+Use git diff and file reads, never git log or PR descriptions.
+Original request: <requester wording, without builder choices or rationale>.
+Factual constraints: <project targets, public contracts, independent sources>.
+Records: <paths; check existence only until the expected matrix is frozen>.
+Check evidence: <paths; read results after freezing, not implementation rationale>.
+Undeclared changes: <change-set paths outside every declaration>.
+Report your frozen matrix before opening the records. End with the domain report
+and one verdict, or explain incomplete execution without attestation.
+```
+
+## Composition and expiry
+
+One builder coordinates all applicable dimensions. Keep their records and verdicts distinct.
+Historical transforming reviews run before final reviews. Independent reviewers can run in
+parallel on one frozen final state, without exchanging rationale. Completion requires all
+applicable dimensions `SOUND` on that same state; one verdict cannot compensate for another.
+
+Any change to a file in a review's scope invalidates it, including prose. Shared files
+invalidate all covering reviews. Without precise scope tracking, invalidate the whole
+change's reviews. Identify the state with a commit plus the staged/unstaged diff and
+untracked file contents or hashes; a clean HEAD alone does not identify a dirty worktree.
+Record/schema/catalog changes also reopen the affected review. No generic orchestrator
+is implied. An external index of scopes, hashes, record paths, checks and responses is enough.
+
+A correction for one dimension moves the change set and therefore expires every verdict of
+the task, because every reviewer's brief covers the whole diff. Corrections are therefore
+batched: address every pending finding of every dimension, then reopen all applicable
+reviews together on one state, frozen while they are in flight so no verdict binds to code
+its reviewer never read. A review filed on a state that moved since it began is void.
+
+If domain requests conflict, identify the incompatible invariants and reopen decisions
+before writing. A dimension that turns non-`SOUND` on a state produced by correcting another
+is a cross-dimension conflict, which the next briefs carry. Stop a repeating conflict for
+user arbitration; never force a verdict. Bound the conflict rounds and the total rounds, and
+send a task that reaches either bound to the user rather than looping.
+
+## Gate and portable execution
+
+Inspect the installed gate's help/capabilities before using a dimension. Never invent CLI
+flags, reuse a different dimension or treat a refused record as an absent gate. A gate
+validates shape, membership and referential integrity; the reviewer owns semantic judgment
+and only attests SOUND. The gate computes its own fingerprints and accepts none. Fix a
+refused record before continuing that workflow.
+
+The suite's own gate is `ai-engineering-gate`, generic by construction: it derives state from
+evidence and holds no domain rule. Enforcement it applies covers omission, drift and stale
+evidence, not a deliberately forged evidence index. A harness Stop hook is advisory by design
+of the harnesses; the lock on publication is the gate's exit code, consumed by a delivery
+pipeline gate or a CI check.
+
+Without a compatible gate, portable completion consists of validated records, successful
+checks and an independent report tied to the examined state. It provides no automatic
+enforcement or lock. If the project's workflow requires gate attestation, an absent or
+unsupported gate leaves that workflow incomplete; portable evidence cannot replace it.
+Keep evidence available through review/correction; do not reconstruct missing historical
+decisions as if they preceded implementation.