Skip to content

CANONICAL-TEMPLATES.adoc

Latest commit

 

History

History
180 lines (135 loc) · 7.72 KB

CANONICAL-TEMPLATES.adoc

File metadata and controls

180 lines (135 loc) · 7.72 KB

Canonical Contractiles And K9 Guide

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?

Table of Contents

1. 1. Canonical Contractile Roles

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 ( with probes, declared → in_progress → done/deferred/retired) AND horizon aspirations ( 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 semantics were absorbed into intend/Intentfile.a2ml as a second section alongside . Items with an observable probe belong in ; horizon-level desires that might never be acted on belong in . A wish can graduate into an intent when a concrete plan materialises.

2. 2. Semantics The Estate Expects

2.1. 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

2.2. 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.

2.3. 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.

2.4. 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.

2.5. 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.

2.6. Intend (north-star: commitments + aspirations)

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

  • — 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.

  • — 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 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. 3. K9 Trust Tiers

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. 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 () and horizon aspirations ().

  • 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. 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.