Skip to content

Commit 6322cd0

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
committed
contractiles: rename intend/Intentfile.a2ml → Intendfile.a2ml; refresh READMEs + CANONICAL-TEMPLATES
Resolves the three deferred contractile-taxonomy decisions (2026-04-17): (Q1) Rename: canonical intend verb now follows the Verbfile.a2ml convention (Mustfile, Trustfile, Dustfile, Adjustfile, Bustfile, Lustfile, Intendfile). Scope is limited to .machine_readable/contractiles/ — the wider ~150-file template sprawl under standards/ (a2ml/**/lust/Intentfile, k9-svc/**, etc.) is flagged as a separate follow-up, not mass-renamed here. (Q2) k9/ placement: kept inside contractiles/ as intended by CANONICAL-TEMPLATES §4 — k9 is the parallel automation surface that validates or enforces the verb declarations. README now states this explicitly ("k9 is not a verb"). (Q3) README refresh: canonical .machine_readable/contractiles/README.adoc, repo-top contractiles/README.adoc, and CANONICAL-TEMPLATES.adoc now list all 7 verbs (must, trust, adjust, dust, bust, intend, lust) + the k9 layer. intend-vs-lust distinction (commitment axis vs aspiration axis) is now documented in-place rather than implicit. Intendfile.a2ml content genericised — removed stale Burble-specific fragment that had leaked into the canonical template. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 2029b40 commit 6322cd0

6 files changed

Lines changed: 248 additions & 69 deletions

File tree

‎.machine_readable/contractiles/README.adoc‎

Lines changed: 96 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,105 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
12
= Contractiles Template Set
23
:toc:
34
:sectnums:
45

5-
This directory contains the generalized contractiles templates. Copy the `.machine_readable/contractiles/` directory into a new repo to establish a consistent operational, validation, trust, recovery, and intent framework.
6+
This directory contains the canonical contractile templates for the
7+
hyperpolymath estate. Copy `.machine_readable/contractiles/` into a new repo
8+
to establish a consistent operational, validation, trust, recovery,
9+
aspiration, and service-automation framework.
10+
11+
Each verb directory holds exactly two files:
12+
13+
* `<Verb>file.a2ml` — the project-specific declaration (data)
14+
* `<verb>.ncl` — the paired Nickel runner (pedigree + schema + run policy)
15+
16+
Anything else in a verb directory is human-only notes or archive; machines
17+
ignore it. Filenames use lowercase verb in the `.ncl` name and PascalCase
18+
verb in the A2ML (e.g. `intend.ncl` + `Intendfile.a2ml`).
19+
20+
== Verbs (7)
21+
22+
[cols="1,2,3", options="header"]
23+
|===
24+
| Verb | A2ML file | Role
25+
26+
| `must`
27+
| `must/Mustfile.a2ml`
28+
| Release-blocking invariants that must hold. Gating — fails block.
29+
30+
| `trust`
31+
| `trust/Trustfile.a2ml`
32+
| Trust boundary, allowed actions, integrity checks. Gating.
33+
34+
| `adjust`
35+
| `adjust/Adjustfile.a2ml`
36+
| Controlled corrective actions — bounded drift tolerances and responses.
37+
38+
| `dust`
39+
| `dust/Dustfile.a2ml`
40+
| Rollback, recovery, and deprecation semantics. Report + act on undo.
41+
42+
| `bust`
43+
| `bust/Bustfile.a2ml`
44+
| Breakage, expiry, and hard-stop conditions. Gating — declares "this is
45+
broken" rather than "this must stay healthy".
46+
47+
| `intend`
48+
| `intend/Intendfile.a2ml`
49+
| Declared next-action commitment — concrete tracked intents with probes
50+
for progress observation. Non-gating (report only).
51+
52+
| `lust`
53+
| `lust/Lustfile.a2ml`
54+
| Aspirations and wishes grouped by horizon (near/mid/far). Distinct from
55+
`intend` — `lust` is wish, `intend` is commitment. Non-gating.
56+
|===
57+
58+
== k9 — Service-Automation Layer (parallel to verbs)
59+
60+
`k9/` is **not** a verb. It sits alongside the verb templates and provides
61+
the graded automation surface that validates or enforces the verb
62+
declarations. Three trust tiers, lowest to highest authority:
63+
64+
* `k9/template-kennel.k9.ncl` — **Kennel**. Pure data. No subprocess, no
65+
filesystem write, no network. Safe for metadata and declarative settings.
66+
* `k9/template-yard.k9.ncl` — **Yard**. Nickel evaluation with contracts and
67+
validation, but no side effects.
68+
* `k9/template-hunt.k9.ncl` — **Hunt**. Full execution surface. Must declare
69+
side effects, support dry-run, and be signed before the estate treats it
70+
as trustworthy automation.
71+
72+
Audit rule: if a repo claims `k9` enforcement, each k9 component must
73+
correspond to a stated contractile (via the `paired_xfile` field), not float
74+
as an unrelated demo.
675

776
== Fill-In Instructions
877

9-
1. Update the Mustfile to reflect your real invariants (paths, schema versions, ports).
10-
2. Replace Trustfile.hs placeholders with your actual key paths and verification commands.
11-
3. Adjust Dustfile handlers to match your rollback and recovery tooling.
12-
4. Update Intentfile to mirror the roadmap you want the system to evolve toward.
78+
When copying this set into a new repo:
79+
80+
1. Replace every template file's placeholders with project-specific content.
81+
2. `Mustfile` — encode real invariants (schema versions, ports, required
82+
checks), not generic samples.
83+
3. `Trustfile` — point at actual keys, policies, and authority boundaries.
84+
4. `Adjustfile` — define the drift tolerances and corrective actions the
85+
repo commits to.
86+
5. `Dustfile` — describe how this repo actually rolls back or retires
87+
behaviour while preserving the audit trail.
88+
6. `Bustfile` — declare real breakage / expiry / hard-stop conditions.
89+
7. `Intendfile` — list tracked next-actions with observable probes.
90+
8. `Lustfile` — list aspirations grouped by near/mid/far horizon.
91+
9. Pair any `k9/*.k9.ncl` with a specific contractile via `paired_xfile`.
92+
93+
== Intend vs Lust — Keep Them Distinct
94+
95+
This is the most common confusion:
1396

14-
== Contents
97+
* `intend` is the **commitment axis**. Items here are tracked next-actions
98+
with probes. Status progresses declared → in_progress → done.
99+
* `lust` is the **aspiration axis**. Items here are wishes grouped by
100+
horizon. Status progresses declared → in_progress → achieved/abandoned.
15101

16-
* `must/Mustfile` - required invariants and validations.
17-
* `trust/Trustfile.hs` - cryptographic verification steps.
18-
* `dust/Dustfile` - rollback and recovery semantics.
19-
* `lust/Intentfile` - future intent and roadmap direction.
102+
If something is concrete enough to have a probe, it belongs in `intend`.
103+
If it is a horizon-level desire that might never be acted on, it belongs
104+
in `lust`. An item can graduate from `lust` to `intend` when a concrete
105+
plan materialises.

‎.machine_readable/contractiles/intend/Intendfile.a2ml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
# Intendfile (A2ML Canonical) — committed next-actions contractile
3+
# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
4+
#
5+
# Paired runner: intend.ncl
6+
# Verb: intend
7+
# Semantics: concrete tracked next-actions the project has committed
8+
# to. Each entry has a description and optionally a probe
9+
# (a shell command indicating done-ness). Status moves
10+
# declared → in_progress → done / deferred / retired.
11+
# Non-gating — this is a report, not a gate. Distinct
12+
# from `lust` which holds wishes/aspirations on the
13+
# horizon axis.
14+
#
15+
# CLI:
16+
# contractile intend run → print status table
17+
# contractile intend progress → diff declared-vs-observed
18+
19+
@abstract:
20+
Generic Intendfile template. Replace every [[intents]] item with a project-
21+
specific next-action commitment. Keep wishes/aspirations in the sibling
22+
Lustfile, not here.
23+
@end
24+
25+
## Purpose
26+
27+
State the declared purpose of the project in one paragraph. This block
28+
should mirror the repository's README lead — do not restate roadmap or
29+
feature lists here.
30+
31+
## Anti-Purpose
32+
33+
This project is NOT:
34+
- A fork or wrapper around another tool (replace if it is, or delete)
35+
- A monorepo (unless explicitly structured as one)
36+
- <add project-specific anti-scope lines here>
37+
38+
## If In Doubt
39+
40+
If you are unsure whether a change is in scope, ask. Sensitive areas:
41+
ABI definitions, license headers, CI workflows.
42+
43+
## Committed next-actions
44+
45+
[[intents]]
46+
id = "example-intent"
47+
description = "Describe one concrete next-action the project commits to"
48+
probe = "echo 'replace with a shell command that signals done-ness'"
49+
status = "declared"
50+
notes = "Optional human notes; leave empty or delete"

‎.machine_readable/contractiles/intend/Intentfile.a2ml‎

Lines changed: 0 additions & 22 deletions
This file was deleted.

‎.machine_readable/contractiles/intend/intend.ncl‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# SPDX-License-Identifier: PMPL-1.0-or-later
22
# Intend — north-star runner (verb is `intend`, not `intent`)
33
#
4-
# Pairs with: Intentfile.a2ml (same directory)
4+
# Pairs with: Intendfile.a2ml (same directory)
55
# Verb: intend
66
# Semantics: declarative aspirations. Not a gate — reports progress toward
77
# target state. Items can be declared / in-progress / done /
@@ -27,7 +27,7 @@
2727
name = "intend-runner",
2828
version = "1.0.0",
2929
description = "Reports progress toward declared future-state intents. Non-gating.",
30-
paired_xfile = "Intentfile.a2ml",
30+
paired_xfile = "Intendfile.a2ml",
3131
author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",
3232
},
3333
},

‎contractiles/CANONICAL-TEMPLATES.adoc‎

Lines changed: 61 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -37,17 +37,32 @@ toc::[]
3737
| Recovery, rollback, deprecation, and traceability semantics.
3838
| If something goes wrong, does this file explain how the repo rolls back or retires behavior without losing the audit trail?
3939

40-
| Intent
41-
| `contractiles/intend/Intentfile.a2ml`
42-
| Canonical A2ML statement of purpose, anti-purpose, and scope.
43-
| Does the declared scope match the README, roadmap, and actual implementation boundary?
44-
45-
| Intent (legacy compatibility)
46-
| `contractiles/lust/Intentfile`
47-
| Plain-text compatibility form of the intent role. Keep only if a repo still needs the legacy template surface.
48-
| If both intent forms exist, are they saying the same thing rather than drifting?
40+
| Adjust
41+
| `contractiles/adjust/Adjustfile.a2ml`
42+
| Drift tolerances and corrective actions the repo commits to when observed state deviates from declared state.
43+
| Are the tolerances realistic, and does each one have a defined corrective action rather than a silent shrug?
44+
45+
| Bust
46+
| `contractiles/bust/Bustfile.a2ml`
47+
| Hard-stop and expiry conditions. Declares "this is broken / expired / must-not-run" rather than "this must stay healthy".
48+
| Are the stop conditions enforced at runtime, or only documented as wishes?
49+
50+
| Intend
51+
| `contractiles/intend/Intendfile.a2ml`
52+
| Concrete tracked next-actions (commitment axis). Probes observe progress; items move declared → in_progress → done.
53+
| Does each intent have an observable probe, and does the declared scope match the README, roadmap, and actual implementation boundary?
54+
55+
| Lust
56+
| `contractiles/lust/Lustfile.a2ml`
57+
| Aspirations (wish axis) grouped by horizon — near, mid, far. Distinct from Intend: lust is wish, intend is commitment.
58+
| Are aspirations separated from commitments, and does each wish have a plausible "why" rather than decoration?
4959
|===
5060

61+
NOTE: `intend` and `lust` are separate axes. Items with an observable probe
62+
belong in `intend`. Horizon-level desires that might never be acted on
63+
belong in `lust`. An item can graduate from `lust` to `intend` when a
64+
concrete plan materialises.
65+
5166
== 2. Semantics The Estate Expects
5267

5368
=== Must
@@ -77,14 +92,39 @@ reversible state changes, and trace-preserving undo semantics are documented.
7792
If a repo claims recovery or staged retirement, `Dustfile` should say how that
7893
happens and what evidence remains behind after the rollback.
7994

80-
=== Intent
95+
=== Adjust
96+
97+
`Adjustfile` defines the drift tolerances the repo accepts and the corrective
98+
actions it takes when observed state deviates from declared state. Each
99+
tolerance should have a concrete action ("drift ≤ X triggers action Y"),
100+
not a vague aspiration to "monitor" something.
101+
102+
=== Bust
103+
104+
`Bustfile` is the hard-stop surface. Where `Mustfile` says "this must hold"
105+
and fails the run when it doesn't, `Bustfile` says "this is broken / expired
106+
/ must-not-run" — declaring brokenness explicitly so downstream consumers
107+
can see it rather than encountering it at runtime. Useful for deprecated
108+
paths that still exist but must not be called.
109+
110+
=== Intend
111+
112+
`Intendfile` holds concrete tracked next-actions on the commitment axis.
113+
Each entry has a description, optionally a probe (a shell command that
114+
indicates done-ness), and a status that progresses declared → in_progress →
115+
done / deferred / retired. The estate treats `Intendfile` as the repo's
116+
public commitment list.
117+
118+
=== Lust
81119

82-
`Intentfile` defines declared purpose and anti-purpose. It should make scope
83-
creep visible: what the repo is for, what it explicitly is not for, and which
84-
areas remain sensitive or out of scope.
120+
`Lustfile` holds aspirations on the wish axis, grouped by horizon (near,
121+
mid, far). Entries have no probes — they are horizon-level desires the
122+
project can see but has not yet committed to. Keeping wishes in `Lustfile`
123+
(rather than in `Intendfile`) prevents the confusion between "we will do X"
124+
and "we would like X to be true some day".
85125

86-
Intent is guidance, not evidence of completion. A repo may promise future work
87-
here, but that future work must not be presented elsewhere as already shipped.
126+
Intent is guidance, not evidence of completion. Neither `Intendfile` nor
127+
`Lustfile` may be presented elsewhere as already-shipped work.
88128

89129
== 3. K9 Trust Tiers
90130

@@ -116,10 +156,13 @@ automation surface that can validate or enforce those declarations.
116156

117157
Estate-level interpretation:
118158

119-
* `Mustfile` provides the invariant claims.
120-
* `Trustfile.a2ml` states who may exercise authority.
159+
* `Mustfile` provides the invariant claims (gating).
160+
* `Trustfile.a2ml` states who may exercise authority (gating).
161+
* `Adjustfile` defines drift tolerances and corrective actions.
121162
* `Dustfile` defines rollback and deprecation semantics.
122-
* `Intentfile` records declared future direction.
163+
* `Bustfile` declares hard-stop / expiry conditions (gating).
164+
* `Intendfile` records committed next-actions.
165+
* `Lustfile` records aspirations grouped by horizon.
123166
* `k9` provides graded automation to validate or enact those contracts.
124167

125168
If a repo claims `k9` enforcement, the automation must correspond to the stated

‎contractiles/README.adoc‎

Lines changed: 39 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,50 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
12
= Contractiles Template Set
23
:toc:
34
:sectnums:
45

5-
This directory contains the canonical top-level contractiles templates.
6+
This directory is the repo-top-level copy of the canonical contractile
7+
templates. The canonical master lives at
8+
`.machine_readable/contractiles/` — see its `README.adoc` for the
9+
full verb and audit-semantics reference, and
10+
link:CANONICAL-TEMPLATES.adoc[Canonical Contractiles And K9 Guide] for
11+
the estate-level audit semantics.
612

7-
For the estate-level meaning of each file and the audit semantics for `k9`,
8-
start with link:CANONICAL-TEMPLATES.adoc[Canonical Contractiles And K9 Guide].
13+
Copy this `contractiles/` directory into a new repo to establish a
14+
consistent operational, validation, trust, recovery, aspiration, and
15+
service-automation framework.
916

10-
Copy the `contractiles/` directory into a new repo to establish a consistent
11-
operational, validation, trust, recovery, and intent framework.
17+
== Template Roles (7 verbs + k9)
1218

13-
== Template Roles
19+
[cols="1,2,3", options="header"]
20+
|===
21+
| Verb | Canonical file | What it declares
1422

15-
* `must/Mustfile` - release-blocking invariants and validation checks.
16-
* `trust/Trustfile.a2ml` - trust boundary, allowed actions, and integrity checks.
17-
* `dust/Dustfile` - rollback, recovery, and deprecation semantics.
18-
* `intend/Intentfile.a2ml` - canonical A2ML statement of purpose and anti-purpose.
19-
* `lust/Intentfile` - legacy/plain-text compatibility form of the intent role.
20-
* `k9/` - Kennel/Yard/Hunt automation templates and examples.
23+
| `must` | `must/Mustfile.a2ml` | Release-blocking invariants. Gating.
24+
| `trust` | `trust/Trustfile.a2ml` | Trust boundary + integrity. Gating.
25+
| `adjust` | `adjust/Adjustfile.a2ml` | Drift tolerances + corrective actions.
26+
| `dust` | `dust/Dustfile.a2ml` | Rollback / recovery / deprecation.
27+
| `bust` | `bust/Bustfile.a2ml` | Breakage / expiry / hard-stop. Gating.
28+
| `intend` | `intend/Intendfile.a2ml` | Tracked next-actions (commitment). Non-gating.
29+
| `lust` | `lust/Lustfile.a2ml` | Aspirations by horizon (wish). Non-gating.
30+
|===
31+
32+
The `k9/` directory sits alongside the verbs and provides the three-tier
33+
automation surface (Kennel / Yard / Hunt) used to validate or enforce the
34+
verb declarations. See link:CANONICAL-TEMPLATES.adoc[] §3.
2135

2236
== Fill-In Rules
2337

24-
1. Update the Mustfile to reflect your real invariants (paths, schema versions, ports).
25-
2. Replace Trustfile placeholders with your actual trust boundary and verification steps.
26-
3. Adjust Dustfile handlers so they describe real rollback and deprecation behavior.
27-
4. Update Intentfile content to match the repo's real scope rather than inherited template text.
28-
5. Use `k9` only when the automation enforces or validates a declared contract rather than acting as unrelated demo code.
38+
1. Every placeholder string in a template must be replaced with
39+
project-specific content before the repo is considered compliant.
40+
2. `Mustfile` must encode invariants that are machine-checkable by the
41+
repo's actual toolchain, not aspirational "we intend to…" clauses.
42+
3. `Trustfile` must name real keys, policies, and authority boundaries.
43+
4. `Dustfile` must describe real rollback / deprecation behaviour,
44+
including what evidence persists after a rollback.
45+
5. `Intendfile` lists concrete tracked next-actions; `Lustfile` lists
46+
horizon-level wishes. If the content belongs in both you have written
47+
it wrong — commitments go in `intend`, aspirations go in `lust`.
48+
6. Use `k9` only where the automation enforces or validates a declared
49+
contractile (pair via `paired_xfile`) rather than acting as unrelated
50+
demo code.

0 commit comments

Comments
 (0)