From c4d542c54e8643869ed10edb3b513f2a748bc791 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Sun, 30 Aug 2026 12:36:06 +0100 Subject: [PATCH 1/3] chore: bump standards workflow pins --- .github/workflows/changelog-reusable.yml | 2 +- .github/workflows/deno-ci-reusable.yml | 2 +- .github/workflows/elixir-ci-reusable.yml | 6 +++--- .github/workflows/mirror.yml | 2 +- .github/workflows/rust-ci-reusable.yml | 8 ++++---- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/.github/workflows/changelog-reusable.yml b/.github/workflows/changelog-reusable.yml index b1e05ad0..a95727ed 100644 --- a/.github/workflows/changelog-reusable.yml +++ b/.github/workflows/changelog-reusable.yml @@ -11,7 +11,7 @@ # Caller example (auto-update CHANGELOG.md on every push to main): # jobs: # changelog: -# uses: hyperpolymath/standards/.github/workflows/changelog-reusable.yml@70cdad0e95bb2366a9b2ae9789c0e377fef6e3ef +# uses: hyperpolymath/standards/.github/workflows/changelog-reusable.yml@571cc734cd69fb846032ec77a662aa8ee4fc32cd # permissions: # contents: write # pull-requests: write diff --git a/.github/workflows/deno-ci-reusable.yml b/.github/workflows/deno-ci-reusable.yml index ebcc3b44..6091375e 100644 --- a/.github/workflows/deno-ci-reusable.yml +++ b/.github/workflows/deno-ci-reusable.yml @@ -24,7 +24,7 @@ # # jobs: # deno-ci: -# uses: hyperpolymath/standards/.github/workflows/deno-ci-reusable.yml@70cdad0e95bb2366a9b2ae9789c0e377fef6e3ef +# uses: hyperpolymath/standards/.github/workflows/deno-ci-reusable.yml@571cc734cd69fb846032ec77a662aa8ee4fc32cd name: Deno CI (reusable) diff --git a/.github/workflows/elixir-ci-reusable.yml b/.github/workflows/elixir-ci-reusable.yml index b4540b9a..287417df 100644 --- a/.github/workflows/elixir-ci-reusable.yml +++ b/.github/workflows/elixir-ci-reusable.yml @@ -34,13 +34,13 @@ # # jobs: # elixir-ci: -# uses: hyperpolymath/standards/.github/workflows/elixir-ci-reusable.yml@70cdad0e95bb2366a9b2ae9789c0e377fef6e3ef +# uses: hyperpolymath/standards/.github/workflows/elixir-ci-reusable.yml@571cc734cd69fb846032ec77a662aa8ee4fc32cd # # With dialyzer + customised versions: # # jobs: # elixir-ci: -# uses: hyperpolymath/standards/.github/workflows/elixir-ci-reusable.yml@70cdad0e95bb2366a9b2ae9789c0e377fef6e3ef +# uses: hyperpolymath/standards/.github/workflows/elixir-ci-reusable.yml@571cc734cd69fb846032ec77a662aa8ee4fc32cd # with: # elixir-version: "1.18" # enable_dialyzer: true @@ -50,7 +50,7 @@ # # jobs: # elixir-ci: -# uses: hyperpolymath/standards/.github/workflows/elixir-ci-reusable.yml@70cdad0e95bb2366a9b2ae9789c0e377fef6e3ef +# uses: hyperpolymath/standards/.github/workflows/elixir-ci-reusable.yml@571cc734cd69fb846032ec77a662aa8ee4fc32cd # with: # working_directory: server diff --git a/.github/workflows/mirror.yml b/.github/workflows/mirror.yml index fdd50e59..92623846 100644 --- a/.github/workflows/mirror.yml +++ b/.github/workflows/mirror.yml @@ -13,5 +13,5 @@ permissions: jobs: mirror: - uses: hyperpolymath/standards/.github/workflows/mirror-reusable.yml@70cdad0e95bb2366a9b2ae9789c0e377fef6e3ef + uses: hyperpolymath/standards/.github/workflows/mirror-reusable.yml@571cc734cd69fb846032ec77a662aa8ee4fc32cd secrets: inherit diff --git a/.github/workflows/rust-ci-reusable.yml b/.github/workflows/rust-ci-reusable.yml index 84683bab..ec2c1d40 100644 --- a/.github/workflows/rust-ci-reusable.yml +++ b/.github/workflows/rust-ci-reusable.yml @@ -20,13 +20,13 @@ # # jobs: # rust-ci: -# uses: hyperpolymath/standards/.github/workflows/rust-ci-reusable.yml@70cdad0e95bb2366a9b2ae9789c0e377fef6e3ef +# uses: hyperpolymath/standards/.github/workflows/rust-ci-reusable.yml@571cc734cd69fb846032ec77a662aa8ee4fc32cd # # With audit + coverage enabled: # # jobs: # rust-ci: -# uses: hyperpolymath/standards/.github/workflows/rust-ci-reusable.yml@70cdad0e95bb2366a9b2ae9789c0e377fef6e3ef +# uses: hyperpolymath/standards/.github/workflows/rust-ci-reusable.yml@571cc734cd69fb846032ec77a662aa8ee4fc32cd # with: # enable_audit: true # enable_coverage: true @@ -36,11 +36,11 @@ # # jobs: # rust-ci-cli: -# uses: hyperpolymath/standards/.github/workflows/rust-ci-reusable.yml@70cdad0e95bb2366a9b2ae9789c0e377fef6e3ef +# uses: hyperpolymath/standards/.github/workflows/rust-ci-reusable.yml@571cc734cd69fb846032ec77a662aa8ee4fc32cd # with: # working_directory: crates/cli # rust-ci-server: -# uses: hyperpolymath/standards/.github/workflows/rust-ci-reusable.yml@70cdad0e95bb2366a9b2ae9789c0e377fef6e3ef +# uses: hyperpolymath/standards/.github/workflows/rust-ci-reusable.yml@571cc734cd69fb846032ec77a662aa8ee4fc32cd # with: # working_directory: crates/server # From e64ad1dafb9117cb4b74e0f89bec1a436591e340 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 1 Sep 2026 22:53:40 +0100 Subject: [PATCH 2/3] =?UTF-8?q?spec(contractile):=20v1.2.0=20=E2=80=94=20r?= =?UTF-8?q?econcile=20against=20the=20deployed=20estate?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Corrects the verb count and adds the first measurement of this spec against the repos that deploy it. The count fossil: prose said "eight verbs" in four places while the layout diagram, the registry note and the April migration note already said six. Left over from the lust -> intend absorption (2026-04-18), which decremented the table but not the sentence above it. New: Deployment Reality section, recording that - the seven contractile documents are one normative spec, one byte- identical mirror, one design successor and four derivatives, not seven rival specs; - MUST.contractile (620 files, s-expression, estate-wide universal invariants) and Mustfile.a2ml (555 files, A2ML, per-repo physical state) are two distinct artefact families sharing verb names, not rival encodings; they co-reside in 101 repositories; - 22% of deployed Mustfile.a2ml sit at the canonical path; - one-per-repo cardinality is violated ~2:1 (must) and ~2.6:1 (trust); - runner coverage is 4% (must) and 2% (trust) — the enforcement loop is open across most of the estate; - three April migrations are half-applied: 90 lust/ dirs survive, 36 Intendfile.a2ml remain, and 75 k9 dirs are still at the pre-ADR-001 path. New: Open Rulings, six owner decisions in dependency order. No deployed file changed. Under the standing amendment mechanism, estate-wide changes are amendments and therefore owner decisions. Status: Draft — awaiting owner ratification. Co-Authored-By: Claude Opus 5 --- docs/CONTRACTILE-SPEC.adoc | 329 ++++++++++++++++++++++++++++++++++++- 1 file changed, 323 insertions(+), 6 deletions(-) diff --git a/docs/CONTRACTILE-SPEC.adoc b/docs/CONTRACTILE-SPEC.adoc index 27a74cdc..3ebedb98 100644 --- a/docs/CONTRACTILE-SPEC.adoc +++ b/docs/CONTRACTILE-SPEC.adoc @@ -8,8 +8,10 @@ :icons: font :source-highlighter: rouge Jonathan D.A. Jewell -v1.1.0, 2026-04-17 +v1.2.0, 2026-09-01 +:status: Draft — awaiting owner ratification +[[preamble]] == Preamble and Scope A **contractile** is a paired artefact that documents and enforces a single @@ -31,7 +33,7 @@ probes. This spec covers: -* The eight contractile verbs and their semantics. +* The six contractile verbs, the k9 exception, and their semantics. * The canonical directory layout and naming rules. * The shared Nickel base (`_base.ncl`) and how verb runners inherit from it. * The `probe` contract (current legacy String form and target structured form). @@ -86,8 +88,9 @@ k9:: == The Verb Set -Eight verbs are defined. Seven follow the standard pattern; k9 is an -exception documented in <>. +Six verbs are defined, plus `k9`, which is an exception documented in +<> and is not a verb contractile. The table below therefore has +seven rows: six verbs and one exception. [cols="1,2,5", options="header"] |=== @@ -135,6 +138,7 @@ exception documented in <>. | NOT a verb contractile. See <>. |=== +[[directory-layout]] == Directory Layout === Standard verb layout @@ -183,6 +187,7 @@ Each verb directory MUST contain exactly: Anything else in a verb directory is human notes or archive; machines ignore it. +[[naming-rules]] == Naming Rules 1. **Verb is always lowercase.** The directory name, the `.ncl` file name, and @@ -445,7 +450,7 @@ superseded by the ADR. === Why k9 is different -The eight verbs each declare *one concern per repo*. k9 is not a concern; it is +The six verbs each declare *one concern per repo*. k9 is not a concern; it is the *graded automation surface* that enforces or validates concern declarations. k9 provides three trust-tier templates that repos copy and instantiate: @@ -508,7 +513,7 @@ When implemented, place as `.machine_readable/contractiles/contractile-meta.ncl` == Registry (`INDEX.a2ml`) `.machine_readable/contractiles/INDEX.a2ml` is the machine-readable catalogue -of all eight verbs. It lists: +of all six verbs plus the k9 exception. It lists: * Verb name and one-line semantics. * The file pair (declaration + runner). @@ -601,6 +606,297 @@ NOTE: The CLI was confirmed present at `reposystem/contractiles/cli/` on 2026-04-17. Verify CLI version compatibility with runner schema version via `contractile --version`. +[[deployment-reality]] +== Deployment Reality (measured 2026-09-01) + +Versions v1.0.0 and v1.1.0 of this document specified a *template*. Until now +the template had never been measured against the estate that deploys it. This +section records that measurement. It is descriptive, not normative: it says +what is on disk, so that the rulings in <> can be made against +evidence rather than assumption. + +Method: `find` over `/home/hyperpolymath/developer/repos`, excluding `.git/` +and `.claude/worktrees/`. Counts are files unless stated otherwise. + +=== Document authority + +Seven documents describe contractiles. They are not seven rival specs. Their +standing is: + +[cols="4,2,4",options="header"] +|=== +| Document | Standing | Note + +| `standards/docs/CONTRACTILE-SPEC.adoc` +| *Normative* +| This document. The single authority for the verb set, layout and naming. + +| `ideas-to-alphas/standards/docs/CONTRACTILE-SPEC.adoc` +| Mirror +| Byte-identical to this file as of 2026-09-01 (`diff -q` reports no + difference). It is a copy, not a fork — but an unpinned copy will drift. + De-duplicate it; do not reconcile it. + +| `contractiles-a2-lab/docs/CONTRACTILE-CYBERNETIC-DESIGN.adoc` +| Design successor +| v2.0.0, and therefore versioned *above* this spec, which invites the + mistake of reading it as the newer authority. It is not: it is a design + exploration (temporal-modal decomposition of the verb set, region-typing, + tropical grading of `intend` tracking-error). Treat it as a migration + target, not a rival — the same disposition applied to `INNERVATION.adoc`. + Its verb counts ("six verbs" at line 44, "five verbs" at line 232) are + design-internal groupings, not competing definitions of the verb set. + +| `a2ml/docs/CONTRACTILES-A2ML-V1.adoc` +| Derivative +| Describes the A2ML encoding of declaration files. Subordinate to this spec + on layout and naming. + +| `ensaid-spec/spec/07-contractiles.adoc` +| Derivative +| Project-local adoption notes. + +| `oblibeny/docs/CONTRACTILES.adoc` +| Derivative +| Project-local, unversioned. + +| `plasma-parser-writer/docs/contractiles.adoc` +| Derivative +| Project-local, unversioned. +|=== + +NOTE: The memory pointer `contractile-two-specs` records the rivalry as +"Nickel/a2ml vs Ada/YAML". No Ada or YAML contractile specification was found +in the estate on 2026-09-01. Either that pointer is stale, or the document is +outside `developer/repos`. Recorded here so the claim is not carried forward +unverified. + +=== Two populations wear the same verb names + +The sharpest finding, and the one that changes what "reconcile" means. There +are two distinct artefact families in the estate. They share verb names but +they are *not* rival encodings of the same contract: + +[cols="2,3,3",options="header"] +|=== +| | `MUST.contractile` | `Mustfile.a2ml` + +| Path | `/.machine_readable/MUST.contractile` | `.../contractiles/must/Mustfile.a2ml` +| Surface | S-expression | A2ML `@`-block +| Length | 91 lines in 142 of 155 copies | 42 lines typical +| Content | Estate-wide *Universal Invariants* — no hardcoded absolute paths, env vars/XDG only, and 24 more | Per-repo *Physical State* contract citing a "UX Manifesto" +| Variance | Boilerplate-uniform: 143 of 155 carry an identical set of 26 `(must ...)` clauses, differing only in the repo name on two lines | Genuinely per-repo: 203 distinct bodies across 555 files +| In spec? | *No.* Named nowhere in this spec or in any owner ruling | Yes — this is the specified artefact +|=== + +Population sizes, whole estate: + +[cols="2,1,1,1,1",options="header"] +|=== +| Verb | `.contractile` | decl `file.a2ml` | `.ncl` runner | runner coverage + +| `must` | 155 | 555 | 26 | 4% +| `trust` | 155 | 805 | 24 | 2% +| `intend` | 155 | 36 (`Intendfile`) / 475 (`Intentfile`) | 24 | 5% +| `adjust` | 155 | 244 | 25 | 10% +| `dust` | *0* | 393 | 24 | 6% +| `bust` | *0* | 183 | 117 | 63% +| *total* | *620* | | | +|=== + +Three things follow. + +First, all 620 `.contractile` files are s-expression — verified individually, +none is in any other surface. They form a coherent, self-consistent family. +They are simply not *this* family. + +Second, the `.contractile` family covers only four verbs. `DUST.contractile` +and `BUST.contractile` do not exist. So it is not a complete parallel +implementation; it is a partial one. + +Third, 101 repositories carry *both* `MUST.contractile` and `Mustfile.a2ml`; +42 carry only the former and 170 only the latter. In those 101 repos a tool +asking "what must hold here?" gets two different answers from two different +files, and this spec tells it to read only one of them. + +The reading this spec adopts: `MUST.contractile` is not a contractile in the +sense defined in <>. It is an *inherited policy layer* — one uniform +set of estate-wide invariants, copied into 155 repositories. Under the owner's +standing rule that per-repo contractiles must *reference* the standards +version rather than duplicate it, 155 identical copies are by definition +drift. The fix is to hoist the invariant set into `standards` and have repos +reference it, which is exactly the open work item on hoisting Universal +Invariants. Ruling 1 in <> puts the question to the owner +rather than deciding it here. + +=== Layout conformance + +The canonical location is `.machine_readable/contractiles//`, which +matches both this spec's layout diagram and the owner's layout ruling. +Measured against `Mustfile.a2ml` (n=555): + +[cols="4,1,3",options="header"] +|=== +| Location | Count | Status + +| `.machine_readable/contractiles/must/` | 120 | *Canonical* +| `.machine_readable/contractiles/` (flat, no verb dir) | 158 | Drift — missing verb directory +| `contractiles/must/` (no `.machine_readable/`) | 76 | Drift — wrong root +| `docs/templates/contractiles/must/` | 59 | Template copies, not deployments +| other (nested, `rs/`, `showcase/`, `validate-action/`) | ~142 | Mixed +|=== + +*22% of deployed `Mustfile.a2ml` sit at the canonical path.* Layout is the +largest single conformance gap and the cheapest to close, because it is a +mechanical move rather than a content change. + +=== Cardinality is violated at scale + +This spec already states (<>) that each verb declares *one +concern per repo*, and the owner's layout ruling states it more strongly: +exactly ONE of each verb per repo, no second copies, no variants, no +per-subdir duplicates, with `ANCHOR.a2ml` the sole exception. + +Measured: 555 `Mustfile.a2ml` across 271 repositories; 805 `Trustfile.a2ml` +across 313 repositories. Neither ratio can be reconciled with one-per-repo. + +The `trust` figure is skewed and should not be read as "trust is the +best-adopted verb": `developer-ecosystem` alone holds 238 of the 805, with +`k9-ecosystem` (21), `a2ml-ecosystem` (20) and `a2ml` (14) next. The bulk is +template farming inside a handful of ecosystem repos, not breadth of adoption. + +=== The declaration/runner gap — the teeth measurement + +The owner's standing position is that a contractile is toothless unless the +loop is closed: declaration, plus a `.ncl` runner, plus a K9 component, plus +CI wiring that fails the build on violation. A declaration alone is advisory +prose that agents skim and ignore. + +The runner-coverage column above is the first measurement of that loop's +second link. Four of six verbs sit at 2–10%. `must` — the hard gate, the verb +whose whole purpose is to block a merge — has a runner for 4% of its +declarations. `trust` has 2%. + +`bust` at 63% is the outlier worth noting: it has the *fewest* declarations +(183) and by far the most runners (117). Bust was the verb with the empty +`Bustfile.a2ml` defect fixed in April; the repair appears to have shipped +runners alongside declarations, which is what the other five verbs did not do. +It is the existence proof that the coverage gap is a deployment failure, not +an intrinsic property. + +Supporting infrastructure is scarcer still: 28 `_base.ncl` and 28 `INDEX.a2ml` +estate-wide. So roughly 28 repositories have a functioning contractile +*system*; the rest hold declaration files. + +*This spec makes no claim that the deployed estate enforces anything.* On the +measured evidence it does not. + +=== Deprecations that never completed + +Two April 2026 migrations were specified in <> and applied +only in part. + +`lust` → `intend` (2026-04-18). *90 `lust/` directories survive*, 65 of them +containing an `Intentfile.a2ml`. The file was renamed in place; the deprecated +directory was never removed. No `lust/` directory contains an `Intendfile`, so +the two migrations were applied in opposite orders in different repos. + +`Intendfile` → `Intentfile` (2026-04-18). *36 `Intendfile.a2ml` remain* across +20 repositories, against 475 correctly-named `Intentfile.a2ml`. Any work item +citing "42 stale locations" should be corrected to 36 files in 20 repos, and +widened to include the 90 `lust/` directories, which are the larger half of +the same unfinished migration. + +A third relocation is also half-applied. `ADR-001-k9-relocation-to-svc.adoc` +(2026-04-18) moved k9 out of `contractiles/` to `.machine_readable/svc/k9/`. +Measured: *94 directories at the new path, 75 still at the old one.* The +Definitions section of this spec records the move; the layout diagram in +<> was never updated and still draws `k9/` inside +`contractiles/`. That diagram is a fossil of the same kind as the verb count +corrected in v1.2.0, and is flagged as ruling 4. + +=== Where this spec and the owner rulings diverge + +Two substantive conflicts, neither resolved here. + +*File cardinality per verb directory.* This spec says a verb directory +contains *exactly two* files — declaration and runner. The owner's layout +ruling specifies a four-file "Trident": `file.a2ml`, `.ncl`, +`.k9.ncl`, and `.manifest.a2ml`. The runners-for-teeth position +supports the larger set, since the K9 component is one of the four links in +the enforcement loop. Given that the two-file form is at 2–10% coverage, the +gap between spec and ruling is currently academic — but it must be closed +before any conformance audit can state a pass criterion. Ruling 2. + +*Accessibility baseline.* This spec's `adjust` row cites WCAG 2.1 AA. The +contractile CLI record cites WCAG 2.2 AA. One of the two is stale. Ruling 5. + +NOTE: The `intend`/`Intentfile` verb-noun mismatch is *not* a divergence. It +is deliberate, owner-confirmed on 2026-04-18, and already documented in +<> rule 3 and in <>. It is recorded here only +because it is repeatedly re-reported as drift. + +=== How changes to deployed contractiles are made + +Nothing in this section authorises editing the 620 `.contractile` or 555 +`Mustfile.a2ml` files. Under the owner's standing amendment mechanism, +contractiles are fully binding until amended, and there are exactly two ways +to depart from one: + +* A *scoped variance* — per-entry, justified, time-bound, with `reason`, + `approved_by`, `scope` and `expires` recorded beside the entry it varies. + Authority: repo maintainer, or session author for session-scoped variances. +* A *formal amendment* — the contractile itself is rewritten and an ADR + records the old text, the new text, the trigger, the migration plan for + dependents, and the effective date. Authority: the owner for estate-wide + changes, the repo maintainer for repo-local ones. + +A variance without an expiry is drift. An amendment without an ADR is drift. +Silently skipping an obligation is neither — it is the failure mode both +mechanisms exist to prevent. The estate-wide changes implied by this section +are amendments, and are therefore owner decisions, which is why they appear +below as rulings rather than as edits. + +[[open-rulings]] +== Open Rulings + +In dependency order. Ruling 1 gates 2 and 3. + +. *The `MUST.contractile` family.* 620 s-expression files across four verbs, + in 143 repositories, 101 of which also carry the specified `Mustfile.a2ml`. + Named in no spec and no ruling. Recommended: recognise it as the inherited + Universal Invariants layer, hoist the uniform 26-clause invariant set into + `standards` as a single referenced policy, and have repos point at it rather + than carry a copy. The alternative — sanction it as a second artefact family + with its own name — requires a name that is not a verb collision. + +. *Files per verb directory: two or four?* This spec says two; the owner's + layout ruling says four (adding `.k9.ncl` and `.manifest.a2ml`). + A conformance audit cannot state a pass criterion until this is settled. + Recommended: adopt the four-file Trident as the target and record the + two-file form as the transitional minimum, since 2–10% runner coverage + means almost nothing currently meets even the two-file bar. + +. *Runner coverage: build the runners, or downgrade the requirement?* At 4% + (`must`) and 2% (`trust`), the spec's central pairing claim is aspirational. + Either the runners get built — `bust` at 63% shows it is achievable — or + this spec should say plainly that the declaration is the deployed artefact + and the runner is a target state. It should not continue to assert a pairing + that 90%+ of the estate does not have. + +. *Ratify the k9 relocation in the layout diagram.* ADR-001 moved k9 to + `.machine_readable/svc/k9/` on 2026-04-18; 94 directories have moved and 75 + have not. The layout diagram in <> still shows the old + position. Recommended: update the diagram and treat the remaining 75 as a + migration backlog item. + +. *WCAG baseline: 2.1 AA or 2.2 AA?* This spec says 2.1; the CLI record says + 2.2. Pick one. + +. *Cardinality enforcement.* One-per-repo is stated in two places and violated + by roughly 2:1 (`must`) and 2.6:1 (`trust`). Confirm the rule, and confirm + that template copies under `docs/templates/` and ecosystem farms are exempt + from the count — otherwise the rule is unenforceable as written. [[migration-notes]] == Migration Notes @@ -671,6 +967,27 @@ update by adding the import line at the top and replacing duplicated pedigree blocks with the merged form. This is backwards-compatible — old runners remain valid. +== Document History + +* *v1.2.0, 2026-09-01* — first reconciliation against the deployed estate. + Corrected the verb count in four places: the prose said "eight verbs" while + the layout diagram, the registry note and the April migration note all + already said six. The count was a fossil of the `lust` → `intend` + absorption of 2026-04-18, which decremented the table but not the sentence + above it. Added <>, recording the first measurement of + this spec against the estate: the document-authority table for the seven + contractile documents; the finding that `MUST.contractile` (620 files) and + `Mustfile.a2ml` (555 files) are two distinct artefact families rather than + rival encodings, co-resident in 101 repositories; 22% layout conformance; + cardinality violated roughly 2:1; and runner coverage of 4% for `must` and + 2% for `trust`. Added <> with six owner decisions in + dependency order. No deployed file was changed: under the standing + amendment mechanism, estate-wide changes are amendments and therefore + owner decisions. + +* *v1.1.0, 2026-04-17* — `_base.ncl` shared base; probe contract; k9 + exception; registry; CLI binding. See <>. + == SPDX and Attribution All files in this spec and the contractile system carry: From 8952c12512c7cf4c274061516fe9186fbf8dad6a Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 1 Sep 2026 23:02:36 +0100 Subject: [PATCH 3/3] =?UTF-8?q?spec(contractile):=20v1.2.1=20=E2=80=94=20c?= =?UTF-8?q?orrect=20the=20document-authority=20table?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The v1.2.0 table classified four documents as project-local derivatives without reading them. Read all four in full; three were misclassified. - ensaid-spec/spec/07-contractiles.adoc is a normative draft with its own RFC 2119 conformance clause and a rival five-tier taxonomy: lust still live, k9 as a peer tier, "any structured format" permitted. - a2ml/docs/CONTRACTILES-A2ML-V1.adoc is the normative contractiles-v1 field-level validation profile and recognises only four of six verbs. - oblibeny/docs/CONTRACTILES.adoc is a homonym: behavioural contracts on the Oblibeny language, unrelated to the verb system. - plasma-parser-writer was correctly classified, and is the only measured instance of reference-not-duplicate working. Added AOP-CONTRACTILE-MAPPING.adoc as an eighth document (carries an unruled Antifile proposal). Added rulings 7-9. Re-verified the ideas-to-alphas mirror as byte-identical after amendment. Co-Authored-By: Claude Opus 5 --- docs/CONTRACTILE-SPEC.adoc | 130 ++++++++++++++++++++++++++++++++----- 1 file changed, 112 insertions(+), 18 deletions(-) diff --git a/docs/CONTRACTILE-SPEC.adoc b/docs/CONTRACTILE-SPEC.adoc index 3ebedb98..b3dd215f 100644 --- a/docs/CONTRACTILE-SPEC.adoc +++ b/docs/CONTRACTILE-SPEC.adoc @@ -8,7 +8,7 @@ :icons: font :source-highlighter: rouge Jonathan D.A. Jewell -v1.2.0, 2026-09-01 +v1.2.1, 2026-09-01 :status: Draft — awaiting owner ratification [[preamble]] @@ -620,8 +620,12 @@ and `.claude/worktrees/`. Counts are files unless stated otherwise. === Document authority -Seven documents describe contractiles. They are not seven rival specs. Their -standing is: +Eight documents in the estate carry "contractile" in their title or subject. +They are not eight rival specs, but neither are they all subordinate notes: +one is a homonym, two carry normative language of their own, and one carries +an unruled proposal. Every entry below was read in full on 2026-09-01; the +earlier draft of this table classified four of them unread, and three of those +four classifications were wrong. [cols="4,2,4",options="header"] |=== @@ -634,8 +638,8 @@ standing is: | `ideas-to-alphas/standards/docs/CONTRACTILE-SPEC.adoc` | Mirror | Byte-identical to this file as of 2026-09-01 (`diff -q` reports no - difference). It is a copy, not a fork — but an unpinned copy will drift. - De-duplicate it; do not reconcile it. + difference, re-verified after amendment). It is a copy, not a fork — but an + unpinned copy will drift. De-duplicate it; do not reconcile it. | `contractiles-a2-lab/docs/CONTRACTILE-CYBERNETIC-DESIGN.adoc` | Design successor @@ -644,25 +648,64 @@ standing is: exploration (temporal-modal decomposition of the verb set, region-typing, tropical grading of `intend` tracking-error). Treat it as a migration target, not a rival — the same disposition applied to `INNERVATION.adoc`. - Its verb counts ("six verbs" at line 44, "five verbs" at line 232) are - design-internal groupings, not competing definitions of the verb set. + Its verb counts are design-internal groupings, not competing definitions: + line 44 reads "the six verbs are not an arbitrary checklist" and agrees + with this spec; line 232's "five verbs" is the subset that region-typing + unifies, with `adjust` excluded as a runtime concern. | `a2ml/docs/CONTRACTILES-A2ML-V1.adoc` -| Derivative -| Describes the A2ML encoding of declaration files. Subordinate to this spec - on layout and naming. +| *Normative, narrower scope* — conflicts +| Not adoption notes. It defines the `contractiles-v1` validation profile: + mandatory sections and named fields per file (`gateway_port`, + `schema_version`, `policy_hash_path`, and others) that this spec does not + contain, plus a JSON emission schema and exit codes. Two conflicts. First, + it recognises *four* files only — Mustfile, Trustfile, Dustfile, Intentfile + — with no `adjust` and no `bust`, so a repo can be `contractiles-v1`-valid + while missing two verbs this spec requires. Second, its worked example + reads `contractiles/trust/Trustfile.a2ml`, the wrong root. Subordinate to + this spec on the verb set, layout and naming; authoritative on field-level + A2ML validation until superseded. | `ensaid-spec/spec/07-contractiles.adoc` -| Derivative -| Project-local adoption notes. - -| `oblibeny/docs/CONTRACTILES.adoc` -| Derivative -| Project-local, unversioned. +| *Rival taxonomy* — conflicts +| Not adoption notes. v0.1.0 Draft, RFC 2119 language, its own conformance + clause. It defines a *five-tier* system — Must, Trust, Dust, *Lust*, *K9* — + against this spec's six verbs plus the k9 exception. Three substantive + divergences: `lust` is live as a tier, though it was deprecated and + absorbed into `intend` on 2026-04-18; `k9` is a peer tier rather than a + documented exception; and S07-3 says declarations "MAY be expressed in any + structured format", against this spec's fixed two-file pattern. Its + reference implementation section sites files at `contractiles/must/` and + `contractiles/lust/` — the wrong root, and a plausible source of the 76 + files measured there. Reconcile or scope explicitly to eNSAID. + +| `patallm-gallery/did-you-actually-do-that/docs/AOP-CONTRACTILE-MAPPING.adoc` +| Essay, carrying a proposal +| Dated 2026-03-01. Maps AOP vocabulary onto the contractile system + (aspect → file type, pointcut → GUID, advice → attestation chain). Mostly a + record and not definitional — but it contains a "Proposed: Antifile" + section and a "Future Contractile Types" section, so it is a live proposal + for an artefact family outside the verb set. See ruling 7. | `plasma-parser-writer/docs/contractiles.adoc` -| Derivative -| Project-local, unversioned. +| Derivative — and the reference-not-duplicate exemplar +| Project-local, unversioned, and explicitly self-marked as a roadmap sketch + predating the identity pivot. Its operational value is the delegation + record: the repo "no longer maintains local copies of Mustfile, Dustfile, + Intentfile, or K9" and defers to shared CLI binaries. That is the + reference-not-duplicate rule working as intended, and the only measured + instance of it. + +| `oblibeny/docs/CONTRACTILES.adoc` +| *Homonym — not this system* +| 511 lines, and unrelated. "Contractile" here means a behavioural contract + on the Oblíbený *language*: six series (C static loop bounds, R + reversibility, E echo types, A affinity, T trace, S static analysis). It + contains no verb, no A2ML declaration, no directory layout and no reference + to this spec. It was miscounted as a derivative because of its filename. + Excluded from the contractile document set; listed here so it is not + re-counted. The name collision is worth resolving, but that is an + Oblíbený decision, not a contractile one. |=== NOTE: The memory pointer `contractile-two-specs` records the rivalry as @@ -897,6 +940,36 @@ In dependency order. Ruling 1 gates 2 and 3. by roughly 2:1 (`must`) and 2.6:1 (`trust`). Confirm the rule, and confirm that template copies under `docs/templates/` and ecosystem farms are exempt from the count — otherwise the rule is unenforceable as written. + +Rulings 7 to 9 arise from reading the other contractile documents in full +(see <>). They are independent of 1 to 6. + +[start=7] +. *The eNSAID five-tier taxonomy.* `ensaid-spec/spec/07-contractiles.adoc` + is a normative draft with its own RFC 2119 conformance clause, and it + defines a different system: five tiers rather than six verbs, `lust` still + live nine months after its deprecation, `k9` as a peer tier rather than an + exception, and declarations permitted in "any structured format". A repo can + conform to it and violate this spec. Recommended: scope it explicitly to + eNSAID panels as a *profile* of this spec, drop `lust` in favour of + `intend`, and align its reference-implementation paths to + `.machine_readable/contractiles/`. The alternative — treat eNSAID as a + genuinely separate governance system — is defensible, but then it should + stop using the word "contractile". + +. *The `contractiles-v1` validation profile.* `a2ml/docs/CONTRACTILES-A2ML-V1.adoc` + is the only document that specifies A2ML *fields*, and it is useful for + exactly that. But it recognises four files and omits `adjust` and `bust`, + so `contractiles-v1` validity is not conformance to this spec. Recommended: + keep it as the field-level validation authority, state in both documents + that it is a profile of this spec rather than a peer, and either add the + two missing verbs or record their omission as deliberate with a reason. + +. *The Antifile proposal.* `AOP-CONTRACTILE-MAPPING.adoc` (2026-03-01) + proposes an `Antifile` artefact and a "Future Contractile Types" set. No + ruling has been made on it and no `Antifile` was found deployed. It is + either a seventh artefact to specify or a proposal to close. Leaving it + open is how the estate acquired the speciation this amendment documents. [[migration-notes]] == Migration Notes @@ -969,6 +1042,27 @@ valid. == Document History +=== v1.2.1 — 2026-09-01 + +Correction to the document-authority table in <>. The +v1.2.0 table classified four documents as project-local derivatives without +reading them; three of those classifications were wrong. + +* `ensaid-spec/spec/07-contractiles.adoc` is a normative draft with its own + conformance clause and a rival five-tier taxonomy, not adoption notes. +* `a2ml/docs/CONTRACTILES-A2ML-V1.adoc` is the normative `contractiles-v1` + field-level validation profile, and recognises only four of the six verbs. +* `oblibeny/docs/CONTRACTILES.adoc` is a homonym — behavioural contracts on + the Oblíbený language — and is not part of this system at all. +* `plasma-parser-writer/docs/contractiles.adoc` was correctly classified, and + is additionally the only measured instance of the reference-not-duplicate + rule working. + +Added `AOP-CONTRACTILE-MAPPING.adoc` as an eighth document; it carries an +unruled `Antifile` proposal. Added rulings 7 to 9 for the two normative +conflicts and the proposal. Re-verified the `ideas-to-alphas` mirror as +byte-identical after amendment. + * *v1.2.0, 2026-09-01* — first reconciliation against the deployed estate. Corrected the verb count in four places: the prose said "eight verbs" while the layout diagram, the registry note and the April migration note all