// SPDX-License-Identifier: CC-BY-SA-4.0
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
= Canonical Contractiles And K9 Guide
Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
:toc: macro
:sectnums:

This document defines the estate-level meaning of the canonical `contractiles/`
templates and the `k9` Kennel/Yard/Hunt tiers. Use it when auditing whether a
repository's declared invariants, trust boundaries, rollback story, and future
intent are real rather than template residue.

The role names are stable even when file formats vary. The audit question is the
same in every repo: does this file encode a real project-specific contract, or
is it still inherited scaffolding?

toc::[]

== 1. Canonical Contractile Roles

[cols="1,1,2,2", options="header"]
|===
| Role | Canonical Template Path | What It Means | Audit Question

| Must
| `contractiles/must/Mustfile`
| Release-blocking invariants and validations. This is where a repo declares the checks that must hold before it can claim a given state.
| Do the checks encode real repo invariants, or are they still generic placeholders?

| Trust
| `contractiles/trust/Trustfile.a2ml`
| Provenance, allowed/denied actions, trust boundary, and integrity checks.
| Does the trust posture match the actual keys, policies, and authority boundaries in the repo?

| Dust
| `contractiles/dust/Dustfile`
| Recovery, rollback, deprecation, and traceability semantics.
| If something goes wrong, does this file explain how the repo rolls back or retires behavior without losing the audit trail?

| Adjust
| `contractiles/adjust/Adjustfile.a2ml`
| Drift tolerances and corrective actions the repo commits to when observed state deviates from declared state.
| Are the tolerances realistic, and does each one have a defined corrective action rather than a silent shrug?

| Bust
| `contractiles/bust/Bustfile.a2ml`
| Hard-stop and expiry conditions. Declares "this is broken / expired / must-not-run" rather than "this must stay healthy".
| Are the stop conditions enforced at runtime, or only documented as wishes?

| Intend
| `contractiles/intend/Intentfile.a2ml`
| North-star: committed next-actions ([[intents]] with probes, declared → in_progress → done/deferred/retired) AND horizon aspirations ([[wishes]] grouped near/mid/far, declared → in_progress → achieved/abandoned).
| Does each intent have an observable probe? Does the declared scope match the README, roadmap, and actual implementation boundary? Are wishes clearly aspirational rather than masquerading as commitments?
|===

NOTE: The `lust` verb was deprecated 2026-04-18 (name had unwanted
associations); its [[wishes]] semantics were absorbed into
`intend/Intentfile.a2ml` as a second section alongside [[intents]].
Items with an observable probe belong in `[[intents]]`; horizon-level
desires that might never be acted on belong in `[[wishes]]`. A wish can
graduate into an intent when a concrete plan materialises.

=== Documentation carve-out — Glama README.md

The estate is `.adoc`-canonical with no duplicate documentation formats
(`doc-format.yml` blocks a `README.md` that sits alongside `README.adoc`).
There is exactly one standing exception:

[NOTE]
====
*Glama README.md carve-out.* The Glama MCP-server directory
(https://glama.ai) requires a `README.md` to index a server and will not
render `README.adoc`. A repository that opts into Glama therefore keeps a
`README.md` *alongside* the canonical `README.adoc`, gated on the presence
of a `glama.json` at the repo root.

* `README.adoc` remains the authored source of truth; `README.md` is
  maintained (regenerated from the `.adoc`) solely to satisfy Glama.
* This is a Glama limitation, *not* an owner-policy change — it does not
  loosen the no-duplicate-format rule for any other file or any repo
  without a `glama.json`.
* Enforced by three coupled checks, all keyed on `glama.json`:
  `doc-format.yml` (skips the duplicate error for `README`),
  `contractiles/must/Mustfile` (`readme-md-glama-carveout` — requires the
  `README.md` when `glama.json` is present), and
  `contractiles/dust/Dustfile` (`preserve: glama-readme` — forbids cleanup
  from deleting it).
====

== 2. Semantics The Estate Expects

=== Must

`Mustfile` is not a checklist of nice-to-haves. It is the release-blocking
surface for invariants that are meant to be machine-checked.

Typical examples:

* schema/version alignment
* parser or ABI integrity checks
* repository-specific placeholder bans
* required proof/test/coverage surfaces

=== Trust

`Trustfile.a2ml` is where a repo states who or what is trusted, what actions are
permitted, and what integrity checks define the boundary. It should be specific
about trust actions and deny lists, not generic reassurance.

=== Dust

`Dustfile` is not generic hygiene text. It is the rollback and deprecation
surface. Estate audits should read it as the place where recovery paths,
reversible state changes, and trace-preserving undo semantics are documented.

If a repo claims recovery or staged retirement, `Dustfile` should say how that
happens and what evidence remains behind after the rollback.

=== Adjust

`Adjustfile` defines the drift tolerances the repo accepts and the corrective
actions it takes when observed state deviates from declared state. Each
tolerance should have a concrete action ("drift ≤ X triggers action Y"),
not a vague aspiration to "monitor" something.

=== Bust

`Bustfile` is the hard-stop surface. Where `Mustfile` says "this must hold"
and fails the run when it doesn't, `Bustfile` says "this is broken / expired
/ must-not-run" — declaring brokenness explicitly so downstream consumers
can see it rather than encountering it at runtime. Useful for deprecated
paths that still exist but must not be called.

=== Intend (north-star: commitments + aspirations)

`Intentfile.a2ml` holds both the commitment axis and the aspiration axis
in one file, in two sections:

* `[[intents]]` — concrete tracked next-actions. Each entry has a
  description, optionally a probe (shell command indicating done-ness),
  and status declared → in_progress → done / deferred / retired. The
  estate treats these as the repo's public commitment list.
* `[[wishes]]` — horizon-level aspirations grouped by near / mid / far.
  Entries have no probes; they are desires the project can see but has
  not yet committed to. Keeping them here prevents confusion between
  "we will do X" and "we would like X to be true some day", while
  consolidating both axes on the single north-star file.

The `lust` verb that previously carried [[wishes]] was deprecated
2026-04-18 and its schema absorbed here.

Intent is guidance, not evidence of completion. `Intentfile` content may
not be presented elsewhere as already-shipped work.

== 3. K9 Trust Tiers

[cols="1,1,2,2", options="header"]
|===
| Tier | Canonical Template | Capability | Audit Expectation

| Kennel
| `contractiles/k9/template-kennel.k9.ncl`
| Pure data. No subprocesses, no filesystem writes, no network access.
| Safe for metadata, declarative settings, and other read-only structured outputs.

| Yard
| `contractiles/k9/template-yard.k9.ncl`
| Nickel evaluation with contracts and validation, but no side effects.
| Use for validated configuration, schemas, and policies that need machine-checked structure.

| Hunt
| `contractiles/k9/template-hunt.k9.ncl`
| Full execution surface with recipes and side effects.
| Must declare side effects clearly, support dry-run review, and be signed before the estate treats it as trustworthy automation.
|===

== 4. How Contractiles And K9 Fit Together

The plain contractiles describe what must be true, what is trusted, how to
roll back, and what the project intends to become. `k9` components are the
automation surface that can validate or enforce those declarations.

Estate-level interpretation:

* `Mustfile` provides the invariant claims (gating).
* `Trustfile.a2ml` states who may exercise authority (gating).
* `Adjustfile` defines drift tolerances and corrective actions.
* `Dustfile` defines rollback and deprecation semantics.
* `Bustfile` declares hard-stop / expiry conditions (gating).
* `Intentfile` records committed next-actions ([[intents]]) and horizon aspirations ([[wishes]]).
* `k9` provides graded automation to validate or enact those contracts.

If a repo claims `k9` enforcement, the automation must correspond to the stated
contractiles rather than floating as an unrelated demo component.

== 5. Minimum Audit Bar

A repo should be marked as incomplete if any of the following remain true:

* the contractile files are still template text with generic sample commands
* `Dustfile` does not describe real rollback or deprecation behavior
* the intent file and roadmap contradict each other
* Hunt-level `k9` components are unsigned or their side effects are undocumented
* the repo claims enforced invariants, but the `Mustfile` and `k9` surfaces do not encode those invariants

Conversely, a repo is in better shape when the contractiles make the actual
project boundaries legible to a reviewer without requiring guesswork.
