feat(contractiles): add six Nickel runners (must/intend/adjust/trust/dust/bust)

hyperpolymath · claude · hyperpolymath · commit bcfc683fe650 · 2026-04-17T13:04:02.000+01:00
One &lt;verb&gt;.ncl runner per contractile dir, paired with the existing
&lt;Verb&gt;file.a2ml. Verb is `intend`, not `intent`. All six typecheck under
`nickel typecheck`.

Each runner declares:
- pedigree: schema version, semantics, security leash, paired xfile
- schema: the shape the paired &lt;Verb&gt;file.a2ml must satisfy (so the
  `contractile` CLI can validate each Xfile via nickel)
- run: dispatcher behaviour (pass/fail gating, report format, approval
  requirements for destructive verbs)

Semantics per runner:
- must:   invariants — hard gate on any failure
- intend: north-star — reports progress, never gates
- adjust: accessibility (WCAG 2.1 AA) — warns by default, deterministic fixes allowed
- trust:  security + authorised safe-hacking probes — hard gate on verification or probe-finds-issue
- dust:   exnovation / removal — proposes deletions, --apply gated on approver
- bust:   error handling + failure recovery — hard gate on missing/broken recovery

Unknown files in each &lt;verb&gt;/ dir are human-only archive; machines ignore per
the contractile layout rule.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.machine_readable/contractiles/adjust/adjust.ncl b/.machine_readable/contractiles/adjust/adjust.ncl
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Adjust — accessibility runner
+#
+# Pairs with: Adjustfile.a2ml (same directory)
+# Verb:       adjust
+# Semantics:  accessibility compliance (WCAG 2.1 AA baseline). Gating where
+#             a deterministic fix exists; advisory where human review needed.
+# CLI:        `contractile adjust check` → run all probes, list violations
+#             `contractile adjust fix`   → apply deterministic fixes where defined
+#
+# Anything else in this directory is human-only notes/archive; machines ignore.
+
+{
+  pedigree = {
+    schema_version = "1.0.0",
+    contractile_verb = "adjust",
+    semantics = "accessibility compliance",
+    security = {
+      leash = 'Kennel,
+      trust_level = "fixes allowed where deterministic",
+      allow_network = false,
+      allow_filesystem_write = true,    # `adjust fix` may write (deterministic patches only)
+      allow_subprocess = true,
+    },
+    metadata = {
+      name = "adjust-runner",
+      version = "1.0.0",
+      description = "Evaluates accessibility requirements from Adjustfile.a2ml. Fixes deterministic items; flags the rest for human review.",
+      paired_xfile = "Adjustfile.a2ml",
+      author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",
+    },
+  },
+
+  schema = {
+    requirements
+      | Array {
+          id | String,
+          description | String,
+          probe | String,
+          status | [| 'declared, 'partial, 'verified, 'failing |] | default = 'declared,
+          compliance | String | optional,       # e.g. "WCAG 2.1 AA"
+          notes | String | optional,
+          fix | String | optional,              # deterministic fix command (optional)
+        },
+  },
+
+  run = {
+    on_pass = "continue",
+    on_any_fail = "continue-with-warnings",   # accessibility is progress-tracked, not a hard gate by default
+    report_format = "a2ml",
+    emit_summary = true,
+    auto_fix_when_available = true,
+  },
+}
diff --git a/.machine_readable/contractiles/bust/bust.ncl b/.machine_readable/contractiles/bust/bust.ncl
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Bust — error-handling / failure-recovery runner
+#
+# Pairs with: Bustfile.a2ml (same directory)
+# Verb:       bust
+# Semantics:  every declared failure mode must have a recovery path that has
+#             been exercised. Runner injects failures (via declared probes)
+#             and verifies the recovery path works. Hard gate on any
+#             failure-mode with missing or broken recovery.
+# CLI:        `contractile bust check`  → list failure modes + recovery status
+#             `contractile bust drill`  → inject declared failures, verify recovery
+#
+# Anything else in this directory is human-only notes/archive; machines ignore.
+
+{
+  pedigree = {
+    schema_version = "1.0.0",
+    contractile_verb = "bust",
+    semantics = "error handling + failure recovery",
+    security = {
+      leash = 'Kennel,
+      trust_level = "controlled failure injection; scoped to system-under-test",
+      allow_network = false,
+      allow_filesystem_write = true,      # drills may write transient state (tmp dirs, test DBs)
+      allow_subprocess = true,
+      injection_scope = "system-under-test-only",
+    },
+    metadata = {
+      name = "bust-runner",
+      version = "1.0.0",
+      description = "Exercises declared failure modes and verifies recovery paths. Hard-gates on any failure mode without working recovery.",
+      paired_xfile = "Bustfile.a2ml",
+      author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",
+    },
+  },
+
+  schema = {
+    failure_modes
+      | Array {
+          id | String,
+          description | String,
+          class | [| 'network, 'disk_full, 'oom, 'timeout, 'partial_write, 'panic, 'crash, 'rollback, 'concurrency |],
+          injection_probe | String,          # command that deterministically causes this failure
+          recovery_probe | String,           # command that verifies recovery (exit 0 = recovered)
+          expected_recovery_time_seconds | Number | default = 30,
+          status | [| 'declared, 'drilled, 'verified, 'failing |] | default = 'declared,
+          notes | String | optional,
+        },
+  },
+
+  run = {
+    on_pass = "continue",
+    on_any_fail = "exit-nonzero",         # missing or broken recovery blocks merge
+    report_format = "a2ml",
+    emit_summary = true,
+    record_recovery_times = true,         # feeds the performance tier
+  },
+}
diff --git a/.machine_readable/contractiles/dust/dust.ncl b/.machine_readable/contractiles/dust/dust.ncl
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Dust — exnovation / code-removal runner
+#
+# Pairs with: Dustfile.a2ml (same directory)
+# Verb:       dust
+# Semantics:  exnovation. Identifies code, docs, files, dependencies that are
+#             candidates for REMOVAL. Advisory by default; can be flipped to
+#             active delete via `contractile dust sweep --apply`.
+# CLI:        `contractile dust find`   → list removal candidates
+#             `contractile dust sweep`  → dry-run removals
+#             `contractile dust sweep --apply` → actually delete (gated)
+#
+# Anything else in this directory is human-only notes/archive; machines ignore.
+
+{
+  pedigree = {
+    schema_version = "1.0.0",
+    contractile_verb = "dust",
+    semantics = "exnovation / removal",
+    security = {
+      leash = 'Kennel,
+      trust_level = "proposes deletion; --apply required to execute",
+      allow_network = false,
+      allow_filesystem_write = true,      # --apply mode writes (deletes)
+      allow_subprocess = true,
+      destructive_mode_requires_flag = "--apply",
+    },
+    metadata = {
+      name = "dust-runner",
+      version = "1.0.0",
+      description = "Identifies and optionally removes exnovation targets listed in Dustfile.a2ml. Destructive mode gated behind --apply.",
+      paired_xfile = "Dustfile.a2ml",
+      author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",
+    },
+  },
+
+  schema = {
+    removal_candidates
+      | Array {
+          id | String,
+          description | String,
+          target | String,                 # file / path / symbol / dep name
+          reason | String,                 # why it's a removal candidate
+          probe | String | optional,       # command that confirms it's still removable
+          status | [| 'declared, 'proposed, 'approved, 'removed |] | default = 'declared,
+          approver | String | optional,    # who signed off (for 'approved / 'removed)
+          notes | String | optional,
+        },
+  },
+
+  run = {
+    on_pass = "continue",
+    on_any_fail = "continue-with-warnings",
+    report_format = "a2ml",
+    emit_summary = true,
+    apply_requires_approval = true,       # only 'approved items get swept, even with --apply
+  },
+}
diff --git a/.machine_readable/contractiles/intend/intend.ncl b/.machine_readable/contractiles/intend/intend.ncl
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Intend — north-star runner (verb is `intend`, not `intent`)
+#
+# Pairs with: Intentfile.a2ml (same directory)
+# Verb:       intend
+# Semantics:  declarative aspirations. Not a gate — reports progress toward
+#             target state. Items can be declared / in-progress / done /
+#             deferred / retired.
+# CLI:        `contractile intend run`      → print status table
+#             `contractile intend progress` → diff declared-vs-observed
+#
+# Anything else in this directory is human-only notes/archive; machines ignore.
+
+{
+  pedigree = {
+    schema_version = "1.0.0",
+    contractile_verb = "intend",
+    semantics = "north-star / aspirational",
+    security = {
+      leash = 'Kennel,
+      trust_level = "read-only reporting",
+      allow_network = false,
+      allow_filesystem_write = false,
+      allow_subprocess = true,      # probe commands may shell out
+    },
+    metadata = {
+      name = "intend-runner",
+      version = "1.0.0",
+      description = "Reports progress toward declared future-state intents. Non-gating.",
+      paired_xfile = "Intentfile.a2ml",
+      author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",
+    },
+  },
+
+  schema = {
+    intents
+      | Array {
+          id | String,
+          description | String,
+          probe | String | optional,     # shell command that indicates done-ness
+          status | [| 'declared, 'in_progress, 'done, 'deferred, 'retired |] | default = 'declared,
+          notes | String | optional,
+          target_date | String | optional,
+        },
+  },
+
+  run = {
+    on_pass = "continue",
+    on_any_fail = "continue",         # never blocks; it's a report
+    report_format = "a2ml",
+    emit_summary = true,
+    emit_diff = true,                 # declared vs observed
+  },
+}
diff --git a/.machine_readable/contractiles/must/must.ncl b/.machine_readable/contractiles/must/must.ncl
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Must — invariants runner
+#
+# Pairs with: Mustfile.a2ml (same directory)
+# Verb:       must (invariant assertion)
+# Semantics:  every check is a hard gate. A single failure blocks merge.
+# CLI:        `contractile must run` → reads Mustfile.a2ml, evaluates each check,
+#             emits pass/fail verdict per item, exits non-zero if any failed.
+#
+# This file is the *schema + runner* that the `contractile` CLI (at
+# /var/mnt/eclipse/repos/reposystem/contractiles/cli/) loads alongside
+# Mustfile.a2ml. Anything else in this directory is human-only notes/archive
+# and MUST be ignored by machines.
+
+{
+  pedigree = {
+    schema_version = "1.0.0",
+    contractile_verb = "must",
+    semantics = "invariant",
+    security = {
+      leash = 'Kennel,
+      trust_level = "read-only verification",
+      allow_network = false,
+      allow_filesystem_write = false,
+      allow_subprocess = true,    # verification probes may shell out (e.g. grep, test -f)
+    },
+    metadata = {
+      name = "must-runner",
+      version = "1.0.0",
+      description = "Evaluates every invariant in the adjacent Mustfile.a2ml as a hard gate.",
+      paired_xfile = "Mustfile.a2ml",
+      author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",
+    },
+  },
+
+  # Contract schema — the shape every Mustfile.a2ml must satisfy.
+  # Used by `contractile must typecheck Mustfile.a2ml`.
+  schema = {
+    invariants
+      | Array {
+          id | String,
+          description | String,
+          probe | String,                          # shell command; exit 0 = pass
+          status | [| 'declared, 'verified, 'failing |] | default = 'declared,
+          severity | [| 'critical, 'high, 'medium |] | default = 'critical,
+          notes | String | optional,
+          fix | String | optional,
+        },
+  },
+
+  # Runner behaviour — consumed by the contractile CLI dispatcher.
+  run = {
+    on_pass = "continue",
+    on_any_fail = "exit-nonzero",     # hard gate
+    report_format = "a2ml",           # emit a2ml report, not json
+    emit_summary = true,
+  },
+}
diff --git a/.machine_readable/contractiles/trust/trust.ncl b/.machine_readable/contractiles/trust/trust.ncl
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: PMPL-1.0-or-later
+# Trust — security + safe-hacking runner
+#
+# Pairs with: Trustfile.a2ml (same directory)
+# Verb:       trust
+# Semantics:  integrity / provenance / security verification PLUS a declared
+#             "safe hacking + testing" section — authorised offensive probes
+#             (pen-test harness runs, chaos-engineering probes) scoped to the
+#             repo under test, NEVER touching external systems.
+# CLI:        `contractile trust verify` → run all verifications (read-only)
+#             `contractile trust probe`  → run declared safe-hacking probes
+#
+# Anything else in this directory is human-only notes/archive; machines ignore.
+
+{
+  pedigree = {
+    schema_version = "1.0.0",
+    contractile_verb = "trust",
+    semantics = "security + provenance + safe-hacking",
+    security = {
+      leash = 'Kennel,
+      trust_level = "verification + authorised-probe",
+      allow_network = false,            # verifications are offline by default
+      allow_filesystem_write = false,   # trust writes NOTHING
+      allow_subprocess = true,
+      authorised_probes_only = true,    # probe section must explicitly list allowed targets
+    },
+    metadata = {
+      name = "trust-runner",
+      version = "1.0.0",
+      description = "Security + provenance verifications plus authorised safe-hacking probes. All probes are scoped to the repo under test; never hits external systems.",
+      paired_xfile = "Trustfile.a2ml",
+      author = "Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>",
+    },
+  },
+
+  schema = {
+    verifications
+      | Array {
+          id | String,
+          description | String,
+          probe | String,                 # read-only; exit 0 = pass
+          status | [| 'declared, 'verified, 'failing |] | default = 'declared,
+          severity | [| 'critical, 'high, 'medium, 'low |] | default = 'high,
+          notes | String | optional,
+        },
+
+    # Safe-hacking + testing section (added 2026-04-17 per user direction).
+    # Each probe here is an ACTIVELY EXECUTED test — fuzz runs, chaos probes,
+    # auth-bypass attempts, injection tests. All scoped to the current repo.
+    safe_hacking
+      | {
+          scope | String,                 # e.g. "this-repo-only" / "localhost"
+          allowed_probe_classes
+            | Array [| 'fuzz, 'property_test, 'chaos, 'auth_bypass, 'injection, 'timing |]
+            | default = [],
+          probes
+            | Array {
+                id | String,
+                class | [| 'fuzz, 'property_test, 'chaos, 'auth_bypass, 'injection, 'timing |],
+                description | String,
+                probe | String,             # command to run the probe
+                expected_outcome | [| 'probe_blocks_attempt, 'probe_finds_no_issue |],
+                timeout_seconds | Number | default = 300,
+                notes | String | optional,
+              }
+            | default = [],
+        }
+      | default = { scope = "this-repo-only", allowed_probe_classes = [], probes = [] },
+  },
+
+  run = {
+    on_pass = "continue",
+    on_any_fail = "exit-nonzero",       # hard gate on verifications
+    safe_hacking_on_unexpected_outcome = "exit-nonzero",  # probe found what it shouldn't = block
+    report_format = "a2ml",
+    emit_summary = true,
+  },
+}
