diff --git a/.machine_readable/anchors/ANCHOR.a2ml b/.machine_readable/anchors/ANCHOR.a2ml new file mode 100644 index 0000000..2a26197 --- /dev/null +++ b/.machine_readable/anchors/ANCHOR.a2ml @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# ANCHOR.a2ml - authoritative anchor for julia-the-viper + +[metadata] +version = "1.0.0" +last-updated = "2026-06-13" + +[anchor] +schema = "hyperpolymath.anchor/1" +repo = "hyperpolymath/julia-the-viper" +authority = "upstream-canonical" +purpose = [ + "Define canonical semantics and policy boundaries for julia-the-viper.", + "Declare what downstream/satellite repos can extend but not redefine.", + "Provide a stable golden path and invariant contract for release readiness.", +] + +[identity] +project = "Julia the Viper" +kind = "language" +one-sentence = "Harvard-architecture, addition-only language that makes code injection grammatically impossible; v2 adds reverse-addition reversibility with Echo loss-lineage." +domain = "programming-languages / security / formal-methods" + +[semantic-authority] +policy = "canonical" +owns = [ + "The Harvard thesis: grammatical Control/Data separation (injection-impossibility).", + "Addition-only Data semantics; subtraction = reverse addition, never a primitive (ADR-0007).", + "Echo reversibility tiering: group→Safe / cancellative→Neutral / idempotent→Breaking (ADR-0007 D6).", + "Invariant definitions and contractiles; reference interpreter/typechecker behaviour.", +] + +[implementation-policy] +allowed = ["Rust", "Lean4", "Idris2", "Zig", "Scheme", "Shell", "Just", "Nickel", "AsciiDoc", "Markdown"] +forbidden = ["TypeScript", "Node.js", "npm", "Python", "Go"] + +[golden-path] +smoke-test-command = [ + "cargo test --all-targets", + "cd jtv_proofs && lake build", + "idris2 --check src/abi/Types.idr", +] +success-criteria = [ + "Rust suite green (3-OS matrix)", + "Lean proofs build; 0 sorry/admit/axiom AND 0 True-typed theorems", + "Idris2 ABI total-checks", + "No unresolved critical security findings", +] + +[satellite-policy] +must-pin-upstream = true +must-declare-authority = true +must-have-anchor = true +must-have-golden-path = true + +[semantic-authority-files] +language-spec = "spec/" +formal-proofs = "jtv_proofs/" +proof-status = "verification/PROOF-CAPABILITY-MATRIX.adoc" +foundational-adr = "docs/design-decisions/0007-addition-only-mandate-and-reversibility-tiering.adoc" diff --git a/.machine_readable/bot_exclusion_registry.a2ml b/.machine_readable/bot_exclusion_registry.a2ml new file mode 100644 index 0000000..76dfa4a --- /dev/null +++ b/.machine_readable/bot_exclusion_registry.a2ml @@ -0,0 +1,414 @@ +# SPDX-License-Identifier: MPL-2.0 +# Bot Exclusion Registry — authoritative estate-wide denylist for hyperpolymath bots. +# +# Canonical location: standards/.machine_readable/bot_exclusion_registry.a2ml +# Schema: bot-exclusion-registry.v1 +# Consumed by: hypatia, robot-repo-automaton, every bot in gitbot-fleet/bots/* +# Enforcement point: robot-repo-automaton (the only bot that pushes/PRs); belt-and- +# braces checks in each Tier-1/Tier-2 bot so comments are gated too. +# +# Three axes — a match on ANY axis blocks the action: +# [external-repos] — specific full_name matches (org/repo) +# [vendored-directory-patterns] — globs that should never be edited regardless of repo +# [remote-origin-patterns] — bail-if-origin-matches patterns (catches local clones +# of upstream toolchains that slipped through the net) +# +# Action classes — fine-grained: a repo/pattern can be `scan-only` but still allow +# comments, or `full-denial` which blocks everything. +# +# Default stance for unknown repos: DEFAULT-ALLOW (scan + act), because the estate +# has ~330 owned repos. Use the `candidates` section to propose additions without +# enforcing until reviewed. + +[registry] +version = "1.0.0" +schema = "bot-exclusion-registry.v1" +created = "2026-04-17" +owner = "Jonathan D.A. Jewell " +enforcement = "single-point-plus-belt-and-braces" +kill-switch-env = "HYPATIA_AUTOMATION" # set to "off" to halt ALL bot writes estate-wide + +[default-stance] +# Applied when no axis matches. +scan = "allow" +comment = "allow" +label = "allow" +pr = "allow" +push = "allow" +merge = "gate-on-confidence" # still honours robot-repo-automaton's tiered thresholds + +# ============================================================================ +# AXIS 1 — external-repos +# Repos where the user has affiliation (collaborator / org-member) but is NOT +# the owning org. These are the "do not embarrass me" repos. All scan-only. +# ============================================================================ + +[[external-repos]] +full_name = "Campus-Advisors/github-education-teacher-training-Hyperpolymath" +owner = "Campus-Advisors" +affiliation = "collaborator" +stance = "scan-only" +reason = "External org (Campus-Advisors). User has collaborator rights; bots must not write." + +[[external-repos]] +full_name = "JoshuaJewell/IDApixiTIK" +owner = "JoshuaJewell" +affiliation = "collaborator" +stance = "scan-only" +reason = "Son's personal namespace (co-developer on IDApTIK). Respect personal ownership." + +[[external-repos]] +full_name = "JoshuaJewell/IDApTIK" +owner = "JoshuaJewell" +affiliation = "collaborator" +archived = true +stance = "scan-only" +reason = "Archived. Son's namespace. Never write." + +[[external-repos]] +full_name = "The-Metadatastician/.github" +owner = "The-Metadatastician" +affiliation = "organization_member" +stance = "scan-only" +reason = "Metadatastician org .github profile. User is member, not owner." + +[[external-repos]] +full_name = "The-Metadatastician/paint-type" +owner = "The-Metadatastician" +affiliation = "organization_member" +stance = "scan-only" +reason = "Metadatastician project. Not hyperpolymath-owned." + +[[external-repos]] +full_name = "The-Metadatastician/the-metadatastician" +owner = "The-Metadatastician" +affiliation = "organization_member" +stance = "scan-only" +reason = "Metadatastician main project. User is org member." + +# ============================================================================ +# AXIS 2 — vendored-directory-patterns +# Glob patterns inside any repo that bots must never edit. Catches vendored +# upstream code that could have slipped through the existing `third-party- +# excludes.sh` (which was per-fix-script, not per-bot). +# ============================================================================ + +[[vendored-directory-patterns]] +pattern = "**/deps/**" +reason = "Elixir/mix deps. Rustler FFI bindings are vendored here." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/vendor/**" +reason = "Generic vendor directory convention." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/third_party/**" +reason = "Google/bazel convention." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/third-party/**" +reason = "Hyphenated variant (common in Rust/C++ monorepos)." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/toolchain/**" +reason = "Toolchain snapshots (rust-toolchain, OCaml switches, Haskell sandboxes)." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/registries/**" +reason = "Package registry caches." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/.cargo/**" +reason = "Cargo registry + config. Bots never touch." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/node_modules/**" +reason = "npm/pnpm/yarn install trees. Never committed, never edited." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/target/**" +reason = "Cargo/Rust build output." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/_build/**" +reason = "Elixir/Erlang build dir." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/.hex/**" +reason = "Hex package cache." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/rustlib/**" +reason = "Rust standard library installation." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/rust-src/**" +reason = "Rust source component (rustup component)." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/.rustup/**" +reason = "Rustup state dir." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/winget-pkgs/**" +reason = "Windows package manifests (fork of upstream) — legacy pattern from third-party-excludes.sh." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/macports-ports/**" +reason = "MacPorts port definitions (fork) — legacy pattern from third-party-excludes.sh." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/compiler-source/**" +reason = "Vendored compiler sources (rustc, ghc, etc.) — legacy pattern from third-party-excludes.sh." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/HOL/**" +reason = "HOL theorem prover source — legacy pattern from third-party-excludes.sh." +stance = "never-edit" + +[[vendored-directory-patterns]] +pattern = "**/.mypy_cache/**" +reason = "mypy type-check cache." +stance = "never-edit" + +# ============================================================================ +# AXIS 3 — remote-origin-patterns +# If the current repo's `origin` matches any of these, every bot must bail. +# Catches the case where a user clones an upstream repo locally under their +# eclipse/repos tree — the local clone doesn't have hyperpolymath in the path, +# but its origin remote does identify it. This is the belt-and-braces check +# for the rust-toolchain scenario. +# ============================================================================ + +[[remote-origin-patterns]] +pattern = "github.com/rust-lang/*" +reason = "Official Rust toolchain / standard library." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/Homebrew/*" +reason = "Homebrew official." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/homebrew/*" +reason = "Homebrew lowercase-variant." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/NixOS/*" +reason = "NixOS / nixpkgs." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/nixos/*" +reason = "NixOS lowercase-variant." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/llvm/*" +reason = "LLVM upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/ocaml/*" +reason = "OCaml upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/elixir-lang/*" +reason = "Elixir upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/erlang/*" +reason = "Erlang/OTP upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/golang/*" +reason = "Go upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/python/*" +reason = "CPython upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/haskell/*" +reason = "Haskell upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/ziglang/*" +reason = "Zig upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/JuliaLang/*" +reason = "Julia upstream (user has many Julia-ecosystem repos; be specific)." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/idris-lang/*" +reason = "Idris upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/coq/*" +reason = "Coq/Rocq upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/leanprover/*" +reason = "Lean upstream." +stance = "full-denial" + +[[remote-origin-patterns]] +pattern = "github.com/agda/*" +reason = "Agda upstream." +stance = "full-denial" + +# ============================================================================ +# CANDIDATES — pending user review, NOT yet enforced. +# These are hyperpolymath-owned forks of upstream repos. Forked-upstream status +# was inferred from the fact that Dependabot is disabled on them (characteristic +# of upstream forks that don't want the noise). Needs user confirmation before +# moving to one of the enforced axes above. +# ============================================================================ + +[candidates] +reason = "18 hyperpolymath-owned repos with Dependabot disabled — signature of upstream forks. Bots should treat as scan-only until user confirms." +status = "awaiting-user-confirmation" +proposed-stance = "scan-only" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-elixir" +proposed-stance = "scan-only" +signature = "dependabot-disabled, name matches awesome-* fork pattern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-gleam" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-haskell" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-idris2" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-lua" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-mcp-servers" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-mcp-servers-1" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern (duplicate?)" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-pandoc" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-rust" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern — particularly important given rust-toolchain concern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-selfhosted" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-v" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/awesome-zig" +proposed-stance = "scan-only" +signature = "dependabot-disabled, awesome-* fork pattern" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/file" +proposed-stance = "scan-only" +signature = "dependabot-disabled, likely fork of file(1) tool" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/info" +proposed-stance = "scan-only" +signature = "dependabot-disabled" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/linguist" +proposed-stance = "scan-only" +signature = "dependabot-disabled, github/linguist fork" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/lua-filters" +proposed-stance = "scan-only" +signature = "dependabot-disabled, pandoc-lua-filters fork" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/rescript" +proposed-stance = "scan-only" +signature = "dependabot-disabled, ReScript compiler fork (user is on ReScript core team)" + +[[candidates.forked-upstreams]] +full_name = "hyperpolymath/servers" +proposed-stance = "scan-only" +signature = "dependabot-disabled, likely MCP servers fork" + +# ============================================================================ +# Enforcement notes +# ============================================================================ + +[enforcement] +primary-enforcement-point = "verification-ecosystem/robot-repo-automaton/src/confidence.rs" +secondary-enforcement-points = [ + "fleet-ecosystem/git-automation-ecosystem/gitbot-fleet/bots/rhodibot/src/main.rs", + "fleet-ecosystem/git-automation-ecosystem/gitbot-fleet/bots/echidnabot/src/main.rs", + "fleet-ecosystem/git-automation-ecosystem/gitbot-fleet/bots/sustainabot/crates/sustainabot-analysis/src/directives.rs", + "fleet-ecosystem/git-automation-ecosystem/gitbot-fleet/bots/glambot/src/main.rs", + "fleet-ecosystem/git-automation-ecosystem/gitbot-fleet/bots/seambot/src/main.rs", + "fleet-ecosystem/git-automation-ecosystem/gitbot-fleet/bots/finishbot/src/main.rs", + "fleet-ecosystem/git-automation-ecosystem/gitbot-fleet/bots/panicbot/src/main.rs", +] +load-order = "read-at-startup, cache-in-memory, reload-on-SIGHUP" +fail-closed = true # if registry can't be loaded, ALL bots refuse to write + +[kill-switch] +env = "HYPATIA_AUTOMATION" +behaviour = "setting to `off`, `disabled`, or `0` halts ALL bot write actions immediately" +check-frequency = "every-action" diff --git a/.machine_readable/contractiles/INDEX.a2ml b/.machine_readable/contractiles/INDEX.a2ml new file mode 100644 index 0000000..98b2aff --- /dev/null +++ b/.machine_readable/contractiles/INDEX.a2ml @@ -0,0 +1,25 @@ +# SPDX-License-Identifier: MPL-2.0 +# INDEX.a2ml — contractile family index for julia-the-viper. +# Author: Jonathan D.A. Jewell + +--- +schema = "hyperpolymath.contractiles/1" +repo = "hyperpolymath/julia-the-viper" +layout = "contractiles/{family}/ trident: {Verb}file.a2ml + {verb}.ncl + {verb}.k9.ncl + {verb}.manifest.a2ml; shared _base.ncl" +migrated = "2026-06-13 from top-level .machine_readable/*.contractile (content preserved)" + +[[families]] +verb = "must" ; authority = "blocking" ; declaration = "must/Mustfile.a2ml" +[[families]] +verb = "trust" ; authority = "blocking" ; declaration = "trust/Trustfile.a2ml" +[[families]] +verb = "adjust" ; authority = "gating" ; declaration = "adjust/Adjustfile.a2ml" +[[families]] +verb = "bust" ; authority = "advisory" ; declaration = "bust/Bustfile.a2ml" +[[families]] +verb = "dust" ; authority = "advisory" ; declaration = "dust/Dustfile.a2ml" +[[families]] +verb = "intend" ; authority = "non-gating" ; declaration = "intend/Intentfile.a2ml" + +[note] +top-level = ".machine_readable/{MUST,TRUST,INTENT,ADJUST}.contractile retained as human-readable companions (standards keeps both forms)." diff --git a/.machine_readable/contractiles/README.adoc b/.machine_readable/contractiles/README.adoc new file mode 100644 index 0000000..9dc2775 --- /dev/null +++ b/.machine_readable/contractiles/README.adoc @@ -0,0 +1,144 @@ +// SPDX-License-Identifier: CC-BY-SA-4.0 += Contractiles Template Set +:toc: +:sectnums: + +This directory contains the canonical contractile templates for the +hyperpolymath estate. Copy `.machine_readable/contractiles/` into a new repo +to establish a consistent operational, validation, trust, recovery, +aspiration, and service-automation framework. + +Each verb directory holds exactly two files: + +* `file.a2ml` — the project-specific declaration (data) +* `.ncl` — the paired Nickel runner (pedigree + schema + run policy) + +Anything else in a verb directory is human-only notes or archive; machines +ignore it. Filenames use lowercase verb in the `.ncl` name and noun-form +PascalCase in the A2ML (e.g. `intend.ncl` + `Intentfile.a2ml`, +`must.ncl` + `Mustfile.a2ml`). + +All verb runners import `_base.ncl` (shared pedigree + run-defaults + probe-schema). +See `docs/CONTRACTILE-SPEC.adoc` for the normative specification. + +== Verbs (6 + k9 exception) + +[cols="1,2,3", options="header"] +|=== +| Verb | A2ML file | Role + +| `must` +| `must/Mustfile.a2ml` +| Release-blocking invariants that must hold. Gating — fails block. + +| `trust` +| `trust/Trustfile.a2ml` +| Trust boundary, allowed actions, integrity checks. Gating. + +| `adjust` +| `adjust/Adjustfile.a2ml` +| Controlled corrective actions — bounded drift tolerances and responses. + +| `dust` +| `dust/Dustfile.a2ml` +| Rollback, recovery, and deprecation semantics. Report + act on undo. + +| `bust` +| `bust/Bustfile.a2ml` +| Breakage, expiry, and hard-stop conditions. Gating — declares "this is + broken" rather than "this must stay healthy". + +| `intend` +| `intend/Intentfile.a2ml` +| North-star: committed next-actions ([[intents]] with probes) AND horizon + aspirations ([[wishes]] grouped near/mid/far). Non-gating (report only). + Absorbed the deprecated `lust` verb 2026-04-18. +|=== + +NOTE: The `lust/` verb was deprecated 2026-04-18 (name had unwanted +associations). Its [[wishes]] semantics live inside `intend/Intentfile.a2ml` +as a second section alongside [[intents]]. Any `lust/` dir encountered in +an estate repo is drift and should be removed. + +== k9 — Service-Automation Layer (EXCEPTION to the one-verbfile rule) + +IMPORTANT: `k9/` is **not a contractile verb** and does NOT follow the +`file.a2ml` + `.ncl` pattern. This is an intentional, documented +exception. Do not apply the naming rule to k9. + +=== Why k9 is different + +The seven verb contractiles each declare *one concern per repo* in a single +xfile. 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: + +[cols="1,1,3", options="header"] +|=== +| File | Trust tier | Description + +| `k9/template-kennel.k9.ncl` +| Kennel +| Pure data. No subprocess, no filesystem write, no network. Safe for + metadata and declarative settings. + +| `k9/template-yard.k9.ncl` +| Yard +| Nickel evaluation with contracts and validation. No side effects. + +| `k9/template-hunt.k9.ncl` +| Hunt +| Full execution surface. Must declare side effects, support dry-run, and + be signed before the estate treats it as trustworthy automation. +|=== + +=== Why the naming rule does not apply + +The one-verb-one-Verbfile rule exists to enforce clean concern separation. +k9 is meta-infrastructure: it does not have a `K9file.a2ml` because it is +not a declarative xfile — it is a template set that instantiates into +specific repos. Applying the rule would produce a meaningless `K9file.a2ml` +with nothing to declare. + +=== Audit rule + +If a repo claims `k9` enforcement, each k9 component in that repo MUST +declare a `paired_xfile` pointing to a specific contractile xfile (e.g. +`../must/Mustfile.a2ml`). Floating k9 components with no paired xfile are +non-conformant. + +See `k9/README.adoc` for the full k9 security model and usage instructions. +See `docs/CONTRACTILE-SPEC.adoc §k9-exception` for the normative statement. + +== Fill-In Instructions + +When copying this set into a new repo: + +1. Replace every template file's placeholders with project-specific content. +2. `Mustfile` — encode real invariants (schema versions, ports, required + checks), not generic samples. +3. `Trustfile` — point at actual keys, policies, and authority boundaries. +4. `Adjustfile` — define the drift tolerances and corrective actions the + repo commits to. +5. `Dustfile` — describe how this repo actually rolls back or retires + behaviour while preserving the audit trail. +6. `Bustfile` — declare real breakage / expiry / hard-stop conditions. +7. `Intentfile` — list tracked next-actions with observable probes + ([[intents]] section) AND horizon aspirations ([[wishes]] section). +8. Pair any `k9/*.k9.ncl` with a specific contractile via `paired_xfile`. + +== Intentfile: Commitments vs Aspirations — Two Sections, One File + +Since 2026-04-18 both axes live inside `intend/Intentfile.a2ml`: + +* `[[intents]]` is the **commitment axis**. Items here are tracked + next-actions with probes. Status progresses + declared → in_progress → done/deferred/retired. +* `[[wishes]]` is the **aspiration axis**. Items here are horizon goals + grouped near/mid/far. Status progresses + declared → in_progress → achieved/abandoned. + +If something is concrete enough to have a probe, it belongs in `[[intents]]`. +If it is a horizon-level desire that might never be acted on, it belongs +in `[[wishes]]`. A wish can graduate to an intent when a concrete plan +materialises. diff --git a/.machine_readable/contractiles/_base.ncl b/.machine_readable/contractiles/_base.ncl new file mode 100644 index 0000000..22306fa --- /dev/null +++ b/.machine_readable/contractiles/_base.ncl @@ -0,0 +1,141 @@ +# SPDX-License-Identifier: MPL-2.0 +# (MPL-2.0 is automatic legal fallback until PMPL is formally recognised) +# +# _base.ncl — Shared contractile base +# +# Provides four named schema fragments imported by every verb runner: +# +# pedigree_schema — canonical pedigree block shape +# status_core_doc — documentation of the shared status trio (String list) +# probe_schema — target structured probe form (spec only; verb files +# still use probe | String with TODO comments) +# run_defaults — default runner behaviour +# +# Usage in a verb runner: +# +# let base = import "../_base.ncl" in +# { +# pedigree = base.pedigree_schema & { +# contractile_verb = "must", +# semantics = "invariant", +# security = { +# leash = 'Kennel, +# trust_level = "read-only verification", +# allow_network = false, +# allow_filesystem_write = false, +# allow_subprocess = true, +# }, +# metadata = { +# name = "must-runner", +# version = "1.0.0", +# description = "...", +# paired_xfile = "Mustfile.a2ml", +# author = "Jonathan D.A. Jewell ", +# }, +# }, +# schema = { ... }, +# run = base.run_defaults & { on_any_fail = "exit-nonzero" }, +# } +# +# See: docs/CONTRACTILE-SPEC.adoc §Shared Base + +{ + # ------------------------------------------------------------------------- + # pedigree_schema + # + # The canonical shape of the `pedigree` block required in every verb runner. + # Verb runners merge this with their verb-specific values using Nickel's `&` + # (right-priority merge). Override contractile_verb, semantics, security.*, + # and metadata.* in each verb. + # ------------------------------------------------------------------------- + pedigree_schema = { + schema_version | String | default = "1.0.0", + contractile_verb | String | default = "UNSET", # MUST override in verb + semantics | String | default = "UNSET", # MUST override in verb + security = { + leash | [| 'Kennel, 'Yard, 'Hunt |] | default = 'Kennel, + trust_level | String | default = "UNSET", # MUST override in verb + allow_network | Bool | default = false, + allow_filesystem_write | Bool | default = false, + allow_subprocess | Bool | default = true, + # verb-specific additional security fields go in the verb's merge override: + # e.g. authorised_probes_only (trust), injection_scope (bust), + # destructive_mode_requires_flag (dust) + }, + metadata = { + name | String | default = "UNSET", # MUST override in verb + version | String | default = "1.0.0", + description | String | default = "UNSET", # MUST override in verb + paired_xfile | String | default = "UNSET", # MUST override in verb + author | String | default = "Jonathan D.A. Jewell ", + }, + }, + + # ------------------------------------------------------------------------- + # status_core_doc + # + # Documents the minimum shared status values present in every verb's status + # enum: declared, verified, failing. + # + # Nickel does not support structural enum extension, so verb files reproduce + # their full enum verbatim in `schema`. This field serves as documentation + # and for tooling that introspects the base. + # + # Verbs that extend status_core (i.e. all except must + trust): + # adjust: + 'partial + # bust: + 'drilled + # dust: 'declared, 'proposed, 'approved, 'removed (non-standard) + # intend: intents: 'declared, 'in_progress, 'done, 'deferred, 'retired + # wishes: 'declared, 'in_progress, 'achieved, 'abandoned + # (the wishes schema was absorbed from the deprecated `lust` + # verb 2026-04-18; lust/ dir removed estate-wide) + # + # See: docs/CONTRACTILE-SPEC.adoc §Per-Verb Extension + # ------------------------------------------------------------------------- + status_core_doc = "status_core values: declared | verified | failing — extended per verb", + + # ------------------------------------------------------------------------- + # probe_schema + # + # The TARGET structured probe form. See: docs/CONTRACTILE-SPEC.adoc §Probe + # + # IMPORTANT: This is a spec-only definition. Existing verb runner files still + # use `probe | String` with a `# TODO: migrate to probe_schema` comment. + # This is a breaking change; migration happens when the CLI supports both + # forms. + # + # Adopters writing new xfiles should prefer the structured form: + # probe = { + # command = "test -f my-file", + # timeout_seconds = 60, + # allowed_exit_codes = [0], + # permission_class = 'read_only, + # } + # ------------------------------------------------------------------------- + probe_schema = { + command | String, + timeout_seconds | Number | default = 300, + allowed_exit_codes | Array Number | default = [0], + permission_class + | [| 'read_only, 'filesystem_write, 'subprocess, 'network |] + | default = 'read_only, + }, + + # ------------------------------------------------------------------------- + # run_defaults + # + # Default runner behaviour. Verb runners merge this with verb-specific + # overrides using Nickel's `&` (right-priority merge). + # + # Most verbs override on_any_fail: + # "exit-nonzero" : hard gate (must, trust, bust, adjust-gating) + # "continue-with-warnings": advisory (dust, adjust) + # "continue" : never gate (intend — covers both intents and wishes) + # ------------------------------------------------------------------------- + run_defaults = { + on_pass = "continue", + on_any_fail = "exit-nonzero", + report_format = "a2ml", + emit_summary = true, + }, +} diff --git a/.machine_readable/contractiles/adjust/Adjustfile.a2ml b/.machine_readable/contractiles/adjust/Adjustfile.a2ml new file mode 100644 index 0000000..5ae784f --- /dev/null +++ b/.machine_readable/contractiles/adjust/Adjustfile.a2ml @@ -0,0 +1,25 @@ +# SPDX-License-Identifier: MPL-2.0 +# Adjustfile — Accessibility & adaptation invariants for julia-the-viper. +# Author: Jonathan D.A. Jewell +# Migrated 2026-06-13 from .machine_readable/ADJUST.contractile (content preserved). +# All ADJUST invariants are implicitly MUST invariants (tracked separately for visibility). + +@abstract: +Accessibility is a first-class concern (INTENT anti-purpose: "NOT only for +able-bodied users with modern hardware"). These adaptation invariants keep +docs, diagnostics, and the playground usable across abilities and hardware. +@end + +## Accessibility +### docs-screen-reader +- description: docs (AsciiDoc/Markdown) remain screen-reader navigable (headings, alt text, no ASCII-art-only meaning) +- severity: high +### diagnostics-not-colour-only +- description: compiler/CI diagnostics never rely on colour alone to convey meaning +- severity: high +### playground-keyboard +- description: the playground (Router Visualization) is keyboard-navigable and not motion-essential +- severity: high +### low-resource +- description: core toolchain runs without GPU / large-RAM assumptions +- severity: medium diff --git a/.machine_readable/contractiles/adjust/adjust.k9.ncl b/.machine_readable/contractiles/adjust/adjust.k9.ncl new file mode 100644 index 0000000..9ff26c9 --- /dev/null +++ b/.machine_readable/contractiles/adjust/adjust.k9.ncl @@ -0,0 +1,166 @@ +# SPDX-License-Identifier: MPL-2.0 +# adjust.k9.ncl — K9 trust-tier component of the adjust trident +# Author: Jonathan D.A. Jewell +# +# Pairs with: Adjustfile.a2ml (declaration) + adjust.ncl (runner). +# +# Verb: adjust (drift tolerances + corrective actions) +# Tier: Yard (validation with subprocess for measurement; +# no mutation beyond auto-fix where declared) +# Authority: advisory (continue-with-warnings; not blocking) +# +# adjust is the tolerance-band verb. Where must says "this MUST hold" +# and trust says "this MUST verify clean" (both binary), adjust says +# "drift ≤ X is acceptable; drift > X triggers action Y". Between them, +# adjust handles the subtle-drift territory that binary verbs can't. +# +# Cardinality: ONE adjust trident per repo. +# +# Failure-mode focus: adjust catches cumulative-small-drift patterns +# (E2 cosmetic churn accumulating into real regression, F2 context +# erosion causing gradual parameter drift). Where must flags "broken +# now", adjust flags "drifting toward broken". + +let base_k9 = import "../k9/template-hunt.k9.ncl" in +let base = import "../_base.ncl" in + +{ + pedigree = base_k9.pedigree_schema & { + contractile_verb = "adjust", + paired_xfile = "../adjust/Adjustfile.a2ml", + paired_runner = "../adjust/adjust.ncl", + + tier = 'Yard, + authority = 'advisory, + + metadata = { + name = "adjust-k9", + version = "1.0.0", + description = "Drift-tolerance + corrective-action runner. Fifth trident instance. First (Yard, advisory) authority pattern.", + paired_xfile = "Adjustfile.a2ml", + paired_runner = "adjust.ncl", + author = "Jonathan D.A. Jewell ", + }, + + security = { + leash = 'Yard, + trust_level = "tolerance measurement + declared auto-fix", + allow_network = false, + allow_filesystem_write_conditional = true, # auto_fix_when_available may edit + allow_subprocess = true, + probe_scope = 'measurement_plus_declared_fix, + }, + }, + + variance_schema = { + entry_id | String, + reason | String, + approved_by | String, + scope | String, + expires | String, + review_notes | String | optional, + # adjust-specific: which tolerance band the variance widens + tolerance_band_widened | String, + widened_to_value | String, + }, + + execution = { + triggers = [ 'session_close, 'on_demand, 'pre_push ], + + per_tolerance = { + measure_drift = true, + record_outcome = true, + respect_variance = true, + # adjust-specific authority: tolerance exceeded → warn, try + # auto-fix if declared, then continue. Never blocks. + on_exceeded = 'warn_and_attempt_fix, + on_auto_fix_applied = 'record_and_continue, + on_auto_fix_unavailable = 'record_as_advisory_drift, + # Cumulative-drift detection (adjust's specialty) + track_drift_trend_over_sessions = true, + flag_accelerating_drift = true, + }, + + evidence_sinks = [ + { kind = 'verisimdb, table = "contractile_executions", + schema = "contractile_execution_v1", + aux_tables = [ "adjust_drift_history" ] }, + { kind = 'drift_log, path = ".machine_readable/6a2/DRIFT.a2ml", + append_only = true }, + ], + + on_close = { + re_measure_all_tolerances = true, + diff_against_last_ratification = true, + emit_drift_entries_for_tolerance_exceeded = true, + surface_expired_variances = true, + surface_accelerating_drift = true, + # adjust is advisory — does NOT block session close. + block_session_close_on_any_drift = false, + }, + + on_open = { + render_summary = 'plain_language, + include_drift_log_from_last_close = true, + include_active_variances = true, + include_recent_anchors = true, + anchor_lookback_weeks = 8, + include_tolerance_trend_summary = true, + + negotiation = { + required = true, + ai_required_inputs = [ + 'timeline_realism, + 'industry_standards, + 'audience_feasibility, + 'resulting_invariants, + 'ecosystem_dependencies, + ], + user_engagement_required = true, + user_engagement_mode = 'per_input_response, + specification_translation = { + ai_produces_spec_form = true, + user_reviews_in_domain_language = true, + schema_authoring_is_ai_responsibility = true, + translation_faithfulness_auditable = true, + }, + }, + + accountability_pledge = { + required = true, + parties = [ + { + role = 'user, + pledge = "I have reviewed the tolerance bands and corrective actions. I accept accountability for reviewing drift warnings rather than muting them, and for re-tuning tolerances via amendment when the intended operating envelope changes.", + signature_required = true, + }, + { + role = 'ai_agent, + pledge = "I will surface tolerance breaches and accelerating-drift patterns at session close; I will propose corrective actions rather than widening tolerances silently; I will require amendment for legitimate tolerance re-tuning, not quiet band-widening.", + signature_required = true, + }, + ], + signed_record_destination = ".machine_readable/6a2/ratification-.a2ml", + must_precede_work = true, + }, + + ratification_record_shape = { + includes_negotiation_transcript = true, + includes_both_pledges = true, + includes_tolerance_bands_snapshot = true, + signed = true, + dated = true, + session_id = 'required, + contract_hash = 'required, + }, + }, + }, + + failure_mode_defenses = [ + 'A1_enthusiasm_capture, + 'C3_helpfulness_inflation, # helpful additions surfaced if they widen tolerances silently + 'C4_modernization_drift, + 'E2_cosmetic_churn, # adjust tracks cumulative churn + 'F2_context_window_erosion, # parameter drift across sessions detected + ], +} diff --git a/.machine_readable/contractiles/adjust/adjust.manifest.a2ml b/.machine_readable/contractiles/adjust/adjust.manifest.a2ml new file mode 100644 index 0000000..289df48 --- /dev/null +++ b/.machine_readable/contractiles/adjust/adjust.manifest.a2ml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: MPL-2.0 +# adjust.manifest.a2ml — trident coherence manifest (adjust verb) for julia-the-viper. +# Author: Jonathan D.A. Jewell + +--- +trident_version = "1.0.0" +verb = "adjust" +semantics = "accessibility adaptation — gating" +cardinality = "one per repo" + +[[files]] +role = "declaration" +path = "Adjustfile.a2ml" +notes = "Adjustfile declaration (content). Migrated/created 2026-06-13." + +[[files]] +role = "runner" +path = "adjust.ncl" +notes = "Verb runner; imports ../_base.ncl (framework, from hyperpolymath/standards)." + +[[files]] +role = "k9_component" +path = "adjust.k9.ncl" +notes = "K9 self-validation component (framework, from hyperpolymath/standards)." + +[cross_refs] +runner_paired_xfile = "Adjustfile.a2ml" + +[signed_by] +user = "Jonathan D.A. Jewell" +date = "2026-06-13" +context = "julia-the-viper contractile migration to the standards contractiles/{family}/ trident layout; content preserved from the prior top-level .machine_readable/ADJUST.contractile where one existed (must/trust/intend/adjust), dust/bust created." diff --git a/.machine_readable/contractiles/adjust/adjust.ncl b/.machine_readable/contractiles/adjust/adjust.ncl new file mode 100644 index 0000000..d6c24f0 --- /dev/null +++ b/.machine_readable/contractiles/adjust/adjust.ncl @@ -0,0 +1,62 @@ +# SPDX-License-Identifier: MPL-2.0 +# 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. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + 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 ", + }, + }, + + schema = { + requirements + | Array { + id | String, + description | String, + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + probe | String, + # status_core values: 'declared, 'verified, 'failing; adjust adds 'partial + 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) + }, + }, + + # Runner behaviour — inherits from base.run_defaults. + # adjust is advisory (continue-with-warnings) not a hard gate. + # auto_fix_when_available is adjust-specific. + run = base.run_defaults & { + 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/Bustfile.a2ml b/.machine_readable/contractiles/bust/Bustfile.a2ml new file mode 100644 index 0000000..881301e --- /dev/null +++ b/.machine_readable/contractiles/bust/Bustfile.a2ml @@ -0,0 +1,29 @@ +# SPDX-License-Identifier: MPL-2.0 +# Bustfile — Adversarial / injection-stress contract for julia-the-viper. +# Author: Jonathan D.A. Jewell +# New 2026-06-13. bust = active "safe-hacking" attempts (outrageous-attack catchment), +# the natural home for JtV's killer property: injection must be grammatically rejected. + +@abstract: +Adversarial probes that MUST fail to breach the Harvard boundary. These are +attempted attacks, not invariants — the security tests that make +"injection is grammatically impossible" falsifiable. +@end + +## Injection attempts (must be rejected) +### control-in-data +- description: attempt to embed a Control construct inside a Data expression — parser MUST reject +- expect: grammatical rejection +- severity: critical +### string-as-code +- description: attempt to evaluate a user string as a ControlStmt — no such grammar path exists +- expect: rejection (no eval/exec constructor) +- severity: critical +### explicit-subtract-token +- description: attempt to use an explicit subtraction operator in user Data syntax — MUST not parse (ADR-0007 D2) +- expect: parse error +- severity: high +### reverse-token-reuse +- description: attempt to consume a reverse/abandon token twice — linear typing MUST reject +- expect: type error +- severity: high diff --git a/.machine_readable/contractiles/bust/bust.k9.ncl b/.machine_readable/contractiles/bust/bust.k9.ncl new file mode 100644 index 0000000..c60a0ae --- /dev/null +++ b/.machine_readable/contractiles/bust/bust.k9.ncl @@ -0,0 +1,160 @@ +# SPDX-License-Identifier: MPL-2.0 +# bust.k9.ncl — K9 trust-tier component of the bust trident +# Author: Jonathan D.A. Jewell +# +# Pairs with: Bustfile.a2ml (declaration) + bust.ncl (runner). +# +# Verb: bust (hard-stop / expiry / "must-not-run") +# Tier: Hunt-read-only (subprocess probes for expiry/state checks) +# Authority: blocking (HARD GATE on declared broken states) +# +# bust is the "this is broken, this has expired, this must not run" +# declarative surface. Where must asserts invariants that must hold, +# bust asserts failure states that must not be re-entered. Complement +# to must: together they bound the "acceptable operating state" from +# above (must) and below (bust). +# +# Cardinality: ONE bust trident per repo. +# +# Failure-mode focus: bust catches deprecated-path-still-called +# patterns (C2 capability collapse attempts where an AI reintroduces +# retired code), expiry-exceeded state (certificates / tokens / grants +# past their expiry), and the "it works, ship it" pattern where a +# caller silently starts using a must-not-run API. + +let base_k9 = import "../k9/template-hunt.k9.ncl" in +let base = import "../_base.ncl" in + +{ + pedigree = base_k9.pedigree_schema & { + contractile_verb = "bust", + paired_xfile = "../bust/Bustfile.a2ml", + paired_runner = "../bust/bust.ncl", + + tier = 'Hunt, + authority = 'blocking, + + metadata = { + name = "bust-k9", + version = "1.0.0", + description = "Hard-stop / expiry / must-not-run gate. Fourth trident instance. Completes the blocking-authority triple (must + trust + bust).", + paired_xfile = "Bustfile.a2ml", + paired_runner = "bust.ncl", + author = "Jonathan D.A. Jewell ", + }, + + security = { + leash = 'Hunt, + trust_level = "read-only expiry + state-check with subprocess", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = true, + probe_scope = 'read_only, + }, + }, + + variance_schema = { + entry_id | String, + reason | String, + approved_by | String, + scope | String, + expires | String, + review_notes | String | optional, + severity_acknowledged | [| 'critical, 'high, 'medium |], + waived_consequence_description | String, + }, + + execution = { + triggers = [ 'session_close, 'on_demand, 'pre_push, 'pre_merge ], + + per_hard_stop = { + run_probe = true, + record_outcome = true, + respect_variance = true, + on_triggered = 'fail, # BLOCKING — bust condition hit = block + severity_escalation = 'honour, + # bust-specific: detect re-introduction of deprecated calls + flag_deprecated_reintroduction = true, + }, + + evidence_sinks = [ + { kind = 'verisimdb, table = "contractile_executions", + schema = "contractile_execution_v1", + aux_tables = [ "bust_triggers_history" ] }, + { kind = 'drift_log, path = ".machine_readable/6a2/DRIFT.a2ml", + append_only = true }, + ], + + on_close = { + re_execute_all_hard_stops = true, + diff_against_last_ratification = true, + emit_drift_entries_for_new_triggers = true, + surface_expired_variances = true, + block_session_close_on_critical_bust = true, + }, + + on_open = { + render_summary = 'plain_language, + include_drift_log_from_last_close = true, + include_active_variances = true, + include_recent_anchors = true, + anchor_lookback_weeks = 8, + include_silent_regressions = true, + + negotiation = { + required = true, + ai_required_inputs = [ + 'timeline_realism, + 'industry_standards, + 'audience_feasibility, + 'resulting_invariants, + 'ecosystem_dependencies, + ], + user_engagement_required = true, + user_engagement_mode = 'per_input_response, + specification_translation = { + ai_produces_spec_form = true, + user_reviews_in_domain_language = true, + schema_authoring_is_ai_responsibility = true, + translation_faithfulness_auditable = true, + }, + }, + + accountability_pledge = { + required = true, + parties = [ + { + role = 'user, + pledge = "I have reviewed the declared hard-stop / expiry / must-not-run conditions. I accept accountability for not calling into must-not-run code paths, not ignoring expired tokens/grants, and not silently reintroducing deprecated patterns. I will raise a variance with severity acknowledgement if an exception is needed.", + signature_required = true, + }, + { + role = 'ai_agent, + pledge = "I will refuse suggestions that reintroduce must-not-run patterns; I will surface bust triggers at session close; I will require variance-with-severity for any legitimate reintroduction of a deprecated path rather than silently allowing it.", + signature_required = true, + }, + ], + signed_record_destination = ".machine_readable/6a2/ratification-.a2ml", + must_precede_work = true, + }, + + ratification_record_shape = { + includes_negotiation_transcript = true, + includes_both_pledges = true, + signed = true, + dated = true, + session_id = 'required, + contract_hash = 'required, + }, + }, + }, + + failure_mode_defenses = [ + 'A1_enthusiasm_capture, + 'C2_capability_collapse, # prevents reintroduction of retired capability + 'C4_modernization_drift, # bust prevents silent re-adoption of deprecated libs + 'D4_error_hiding, + 'E1_refactor_stampede, # refactor that reintroduces deprecated path caught + 'F1_across_session_forgetting, # bust triggers persist across sessions + ], +} diff --git a/.machine_readable/contractiles/bust/bust.manifest.a2ml b/.machine_readable/contractiles/bust/bust.manifest.a2ml new file mode 100644 index 0000000..858d916 --- /dev/null +++ b/.machine_readable/contractiles/bust/bust.manifest.a2ml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: MPL-2.0 +# bust.manifest.a2ml — trident coherence manifest (bust verb) for julia-the-viper. +# Author: Jonathan D.A. Jewell + +--- +trident_version = "1.0.0" +verb = "bust" +semantics = "adversarial probe — advisory" +cardinality = "one per repo" + +[[files]] +role = "declaration" +path = "Bustfile.a2ml" +notes = "Bustfile declaration (content). Migrated/created 2026-06-13." + +[[files]] +role = "runner" +path = "bust.ncl" +notes = "Verb runner; imports ../_base.ncl (framework, from hyperpolymath/standards)." + +[[files]] +role = "k9_component" +path = "bust.k9.ncl" +notes = "K9 self-validation component (framework, from hyperpolymath/standards)." + +[cross_refs] +runner_paired_xfile = "Bustfile.a2ml" + +[signed_by] +user = "Jonathan D.A. Jewell" +date = "2026-06-13" +context = "julia-the-viper contractile migration to the standards contractiles/{family}/ trident layout; content preserved from the prior top-level .machine_readable/BUST.contractile where one existed (must/trust/intend/adjust), dust/bust created." diff --git a/.machine_readable/contractiles/bust/bust.ncl b/.machine_readable/contractiles/bust/bust.ncl new file mode 100644 index 0000000..fc8cb8c --- /dev/null +++ b/.machine_readable/contractiles/bust/bust.ncl @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: MPL-2.0 +# 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. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + 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 ", + }, + }, + + schema = { + failure_modes + | Array { + id | String, + description | String, + class | [| 'network, 'disk_full, 'oom, 'timeout, 'partial_write, 'panic, 'crash, 'rollback, 'concurrency |], + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + injection_probe | String, # command that deterministically causes this failure + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + recovery_probe | String, # command that verifies recovery (exit 0 = recovered) + expected_recovery_time_seconds | Number | default = 30, + # status_core values: 'declared, 'verified, 'failing; bust adds 'drilled + status | [| 'declared, 'drilled, 'verified, 'failing |] | default = 'declared, + notes | String | optional, + }, + }, + + # Runner behaviour — inherits from base.run_defaults. + # bust adds record_recovery_times for performance tier feeding. + run = base.run_defaults & { + 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/Dustfile.a2ml b/.machine_readable/contractiles/dust/Dustfile.a2ml new file mode 100644 index 0000000..2ad7c4e --- /dev/null +++ b/.machine_readable/contractiles/dust/Dustfile.a2ml @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: MPL-2.0 +# Dustfile — Deprecation & recovery semantics for julia-the-viper. +# Author: Jonathan D.A. Jewell +# New 2026-06-13 (jtv referenced DUST in prose but had no Dustfile). + +@abstract: +What is deprecated/retired and how it is wound down. DUST is advisory +(continue-with-warnings); a feature's MUST invariants stay active until it is +fully removed. +@end + +## Retired +### embedded-decision-sublanguage +- status: removed +- description: the in-grammar Decision sublanguage (ADR-0002) — superseded by PataCL (ADR-0006, Delta pivot 2026-04-19) +### top-level-contractile-layout +- status: deprecated +- description: top-level .machine_readable/*.contractile — superseded by contractiles/{family}/ trident layout (this migration, 2026-06-13); top-level kept for human reference per standards diff --git a/.machine_readable/contractiles/dust/dust.k9.ncl b/.machine_readable/contractiles/dust/dust.k9.ncl new file mode 100644 index 0000000..ef21668 --- /dev/null +++ b/.machine_readable/contractiles/dust/dust.k9.ncl @@ -0,0 +1,171 @@ +# SPDX-License-Identifier: MPL-2.0 +# dust.k9.ncl — K9 trust-tier component of the dust trident +# Author: Jonathan D.A. Jewell +# +# Pairs with: Dustfile.a2ml (declaration) + dust.ncl (runner). +# +# Verb: dust (rollback / recovery / deprecation) +# Tier: Yard (audit + structural checks; destructive +# actions gated behind --apply flag + +# explicit per-item approval) +# Authority: advisory (continue-with-warnings) +# +# dust is the retirement + audit-trail verb. Rollback paths, deprecation +# markers, evidence-preservation semantics. Where bust declares +# "broken, don't run", dust declares "how to safely undo / retire / roll +# back". Complement to bust — bust marks the dead end, dust describes +# the exit ramp. +# +# Cardinality: ONE dust trident per repo. +# +# Failure-mode focus: dust is the audit-trail preservation verb — +# defends against E1 refactor stampede (check audit trail still +# intact) and against silent removal (anything removed must have a +# rollback path; anything retired must preserve the evidence of its +# previous existence). + +let base_k9 = import "../k9/template-hunt.k9.ncl" in +let base = import "../_base.ncl" in + +{ + pedigree = base_k9.pedigree_schema & { + contractile_verb = "dust", + paired_xfile = "../dust/Dustfile.a2ml", + paired_runner = "../dust/dust.ncl", + + tier = 'Yard, + authority = 'advisory, + + metadata = { + name = "dust-k9", + version = "1.0.0", + description = "Rollback + deprecation + audit-trail runner. Sixth trident instance — completes the full verb set.", + paired_xfile = "Dustfile.a2ml", + paired_runner = "dust.ncl", + author = "Jonathan D.A. Jewell ", + }, + + security = { + leash = 'Yard, + trust_level = "audit-trail verification + structural checks", + allow_network = false, + # dust is the verb that ACTUALLY wants filesystem write — to + # execute declared rollback/removal — but only behind explicit + # --apply flag + per-item approval. Default is dry-run. + allow_filesystem_write_conditional = true, + allow_subprocess = true, + destructive_action_gating = { + default_mode = 'dry_run, + requires_flag = "--apply", + requires_per_item_approval = true, + approval_mechanism = 'explicit_user_signature, + }, + }, + }, + + variance_schema = { + entry_id | String, + reason | String, + approved_by | String, + scope | String, + expires | String, + review_notes | String | optional, + rollback_path_preserved | Bool, # dust-specific: did the variance preserve rollback? + }, + + execution = { + triggers = [ 'session_close, 'on_demand ], + + per_retirement = { + verify_rollback_path_documented = true, + verify_audit_trail_preserved = true, + respect_variance = true, + on_rollback_path_missing = 'warn, # advisory, not block + on_audit_trail_broken = 'warn, # advisory, not block + # dust-specific: flag any retirement that has been requested but + # lacks proper rollback documentation + flag_unsafe_retirement = true, + }, + + evidence_sinks = [ + { kind = 'verisimdb, table = "contractile_executions", + schema = "contractile_execution_v1", + aux_tables = [ "dust_retirement_history" ] }, + { kind = 'drift_log, path = ".machine_readable/6a2/DRIFT.a2ml", + append_only = true }, + ], + + on_close = { + re_verify_all_retirement_paths = true, + diff_against_last_ratification = true, + emit_drift_entries_for_missing_rollback = true, + emit_drift_entries_for_broken_audit_trail = true, + surface_expired_variances = true, + block_session_close_on_any_drift = false, # advisory + }, + + on_open = { + render_summary = 'plain_language, + include_drift_log_from_last_close = true, + include_active_variances = true, + include_recent_anchors = true, + anchor_lookback_weeks = 8, + + negotiation = { + required = true, + ai_required_inputs = [ + 'timeline_realism, + 'industry_standards, + 'audience_feasibility, + 'resulting_invariants, + 'ecosystem_dependencies, + ], + user_engagement_required = true, + user_engagement_mode = 'per_input_response, + specification_translation = { + ai_produces_spec_form = true, + user_reviews_in_domain_language = true, + schema_authoring_is_ai_responsibility = true, + translation_faithfulness_auditable = true, + }, + }, + + accountability_pledge = { + required = true, + parties = [ + { + role = 'user, + pledge = "I have reviewed the declared rollback paths and deprecation markers. I accept accountability for preserving audit trails when retiring code, and for ensuring every retired capability has a documented rollback path. I will not silently delete evidence of prior state.", + signature_required = true, + }, + { + role = 'ai_agent, + pledge = "I will verify audit-trail preservation in any retirement / rollback / deprecation I perform; I will refuse silent deletion of prior-state evidence; I will require rollback-path documentation before accepting a retirement request; I will operate in dry-run mode by default and require explicit --apply + per-item approval for destructive actions.", + signature_required = true, + }, + ], + signed_record_destination = ".machine_readable/6a2/ratification-.a2ml", + must_precede_work = true, + }, + + ratification_record_shape = { + includes_negotiation_transcript = true, + includes_both_pledges = true, + includes_retirement_schedule = true, + signed = true, + dated = true, + session_id = 'required, + contract_hash = 'required, + }, + }, + }, + + failure_mode_defenses = [ + 'A1_enthusiasm_capture, + 'C2_capability_collapse, # retirement without rollback path = capability collapse + 'D5_sycophancy, # AI won't agree to silent deletion + 'E1_refactor_stampede, # audit trail preservation check + 'E2_cosmetic_churn, + 'F1_across_session_forgetting, # retirement history tracked cross-session + ], +} diff --git a/.machine_readable/contractiles/dust/dust.manifest.a2ml b/.machine_readable/contractiles/dust/dust.manifest.a2ml new file mode 100644 index 0000000..081abe5 --- /dev/null +++ b/.machine_readable/contractiles/dust/dust.manifest.a2ml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: MPL-2.0 +# dust.manifest.a2ml — trident coherence manifest (dust verb) for julia-the-viper. +# Author: Jonathan D.A. Jewell + +--- +trident_version = "1.0.0" +verb = "dust" +semantics = "deprecation — advisory" +cardinality = "one per repo" + +[[files]] +role = "declaration" +path = "Dustfile.a2ml" +notes = "Dustfile declaration (content). Migrated/created 2026-06-13." + +[[files]] +role = "runner" +path = "dust.ncl" +notes = "Verb runner; imports ../_base.ncl (framework, from hyperpolymath/standards)." + +[[files]] +role = "k9_component" +path = "dust.k9.ncl" +notes = "K9 self-validation component (framework, from hyperpolymath/standards)." + +[cross_refs] +runner_paired_xfile = "Dustfile.a2ml" + +[signed_by] +user = "Jonathan D.A. Jewell" +date = "2026-06-13" +context = "julia-the-viper contractile migration to the standards contractiles/{family}/ trident layout; content preserved from the prior top-level .machine_readable/DUST.contractile where one existed (must/trust/intend/adjust), dust/bust created." diff --git a/.machine_readable/contractiles/dust/dust.ncl b/.machine_readable/contractiles/dust/dust.ncl new file mode 100644 index 0000000..36aa89b --- /dev/null +++ b/.machine_readable/contractiles/dust/dust.ncl @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: MPL-2.0 +# 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. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + 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 ", + }, + }, + + schema = { + removal_candidates + | Array { + id | String, + description | String, + target | String, # file / path / symbol / dep name + reason | String, # why it's a removal candidate + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + probe | String | optional, # command that confirms it's still removable + # dust has a non-standard status progression (no 'verified): + # 'declared → 'proposed → 'approved → 'removed + status | [| 'declared, 'proposed, 'approved, 'removed |] | default = 'declared, + approver | String | optional, # who signed off (for 'approved / 'removed) + notes | String | optional, + }, + }, + + # Runner behaviour — inherits from base.run_defaults. + # dust is advisory; apply_requires_approval is dust-specific. + run = base.run_defaults & { + 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/Intentfile.a2ml b/.machine_readable/contractiles/intend/Intentfile.a2ml new file mode 100644 index 0000000..da070ef --- /dev/null +++ b/.machine_readable/contractiles/intend/Intentfile.a2ml @@ -0,0 +1,35 @@ +# SPDX-License-Identifier: MPL-2.0 +# Intentfile — Purpose, anti-purpose, and roadmap intents for julia-the-viper. +# Author: Jonathan D.A. Jewell +# Migrated 2026-06-13 from .machine_readable/INTENT.contractile (content preserved). +# (intend absorbs the deprecated `lust` wishes schema, 2026-04-18.) + +@abstract: +JtV is a Harvard-architecture language separating Control (Turing-complete) +from Data (total, addition-only) to make code injection grammatically +impossible — a universal extender for injection-resistant retrofits. v2 adds +reverse-addition reversibility with Echo loss-lineage. +@end + +## Purpose +### is +- description: grammatically injection-proof, addition-only, total Data + Turing Control; universal AOLD extender; v2 reverse-addition + Echo lineage; compile-time decisions delegated to PataCL (ADR-0006) + +## Anti-purpose (prevents scope creep) +### is-not +- description: NOT general-purpose; NOT ergonomic at the expense of the Harvard thesis; does NOT embed a compile-time decision language (that is PataCL); Data is NOT Turing-complete (would break totality); does NOT replace Rust/Zig/Ada + +## Architectural invariants (must not be reversed) +### invariants +- description: Harvard separation; addition-only Data (reverse addition, no subtract token); totality; injection-impossibility by grammar; v2 reverse blocks (snapshot + linear token); PataCL delegation; Idris2 ABI; Zig FFI emission + +## Roadmap intents (wishes) +### intents +- governance-hardening: in_progress +- number-system-semantics: declared # ADR-0007 D6 (algebra → Echo tier) +- v2-c-token-residue-reversal: declared # ADR-0007 D5 Neutral tier +- echo-as-function-effect-b: deferred + +## Ask before touching +### sensitive +- description: spec/ grammar + LANGUAGE_SPECIFICATION; crates/jtv-core/src/grammar.pest; docs/design-decisions/*.adoc (ADR-0006, ADR-0007); jtv_proofs/*; .machine_readable/6a2/*.a2ml (update all six together) diff --git a/.machine_readable/contractiles/intend/intend.k9.ncl b/.machine_readable/contractiles/intend/intend.k9.ncl new file mode 100644 index 0000000..5b0c295 --- /dev/null +++ b/.machine_readable/contractiles/intend/intend.k9.ncl @@ -0,0 +1,250 @@ +# SPDX-License-Identifier: MPL-2.0 +# intend.k9.ncl — K9 trust-tier component of the intend trident +# Author: Jonathan D.A. Jewell +# +# Pairs with: Intentfile.a2ml (declaration) + intend.ncl (runner). +# Trident completeness is a hard precondition — a repo shipping +# Intentfile without this file AND its runner is an invalid trident; +# the contractile CLI's verify gate refuses partial publication. +# +# Verb: intend (north star — commitments + aspirations) +# Tier: Hunt (capability: subprocess probes may shell out) +# Authority: reporting (never blocks; drift-log only) +# +# Cardinality: ONE intend trident per repo (see feedback_contractile_ +# layout_rules.md). ANCHOR.a2ml is the sole multi-instance exception — +# it is NOT a verb contractile. +# +# Design commitments baked in (see memory trail 2026-04-18 for full +# context; key files referenced by name in annotations below): +# * α two-axis (tier × authority) — structurally separate capability +# from authority so "Hunt tier = can override" is impossible. +# * Variance schema first-class, not comment markers +# (feedback_audit_tool_suppression_design.md — structural > markers). +# * Sessional drift detection hooks (on_close, on_open). +# * Ratification at session open; drift log at session close. +# * Evidence sinks: VeriSimDB (queryable) + 6a2/DRIFT.a2ml (repo-local). +# * Failure-mode defenses cross-referenced to the AI failure catalog. + +let base_k9 = import "../k9/template-hunt.k9.ncl" in +let base = import "../_base.ncl" in + +{ + pedigree = base_k9.pedigree_schema & { + contractile_verb = "intend", + paired_xfile = "../intend/Intentfile.a2ml", + paired_runner = "../intend/intend.ncl", + + # α two-axis declaration — capability × authority. + # intend is Hunt-capable (probes shell out) but reporting-authority + # (never blocks). must/trust/bust will declare (Hunt, blocking); + # adjust/dust will declare (Yard, advisory). Splitting the axes + # means "I'm Hunt-tier so I can override everything" is structurally + # impossible — authority is a separate field. + tier = 'Hunt, + authority = 'reporting, + + metadata = { + name = "intend-k9", + version = "2.0.0", # 1.0.0 (2026-04-18 AM): initial trident. + # 2.0.0 (2026-04-18 PM): negotiation + + # accountability + plain-language-translation + # schema baked into on_open — prerequisite for + # the adversarial Gemini+Copilot drift pilot. + description = "Executes Intentfile probes + emits drift log. Non-gating; reporting authority only. on_open hook implements negotiation-ratification-accountability protocol.", + paired_xfile = "Intentfile.a2ml", + paired_runner = "intend.ncl", + author = "Jonathan D.A. Jewell ", + }, + + security = { + leash = 'Hunt, + trust_level = "subprocess + filesystem-read", + allow_network = false, + allow_filesystem_write = false, # evidence sinks are indirected + allow_subprocess = true, + }, + }, + + # ------------------------------------------------------------------- + # Variance schema — P-shape scoped exceptions per entry. + # A variance suppresses a specific intent's or wish's obligation for a + # reason, with approver + expiry. Expired variance = effective + # re-imposition of the obligation. Unmet intent without a variance = + # drift, logged to the drift log. + # Per user 2026-04-18: variances are structural, not magic-comment + # markers — markers are gameable. + # ------------------------------------------------------------------- + variance_schema = { + entry_id | String, # which intent/wish id the variance applies to + reason | String, + approved_by | String, + scope | String, # path glob | session-id | "until-" + expires | String, # absolute date or condition + review_notes | String | optional, + }, + + # ------------------------------------------------------------------- + # Execution policy + # ------------------------------------------------------------------- + execution = { + # When the component runs. + # session_close is mandatory (the "picked up sessionally" check). + triggers = [ 'session_close, 'on_demand, 'pre_push ], + + # Per-intent execution. + per_intent = { + run_probe = true, + record_outcome = true, + respect_variance = true, # active variance suppresses failure + on_unmet = 'log_drift, # never 'fail — authority = reporting + }, + + # Per-wish execution (wishes are non-probeable; horizon-group only). + per_wish = { + run_probe = false, + emit_horizon_summary = true, + # Vertical alignment soft-check per user_6a2_is_contractile_ought.md: + # highest-level alignment is meta ↔ north-star (soft), not hard gate. + check_alignment_with_META = true, + }, + + # Evidence sinks — BOTH written, every execution. + # VeriSimDB = queryable machine record (feedback_verisimdb_policy.md). + # 6a2/DRIFT.a2ml = repo-local append-only drift log (feedback_sessional_ + # drift_detection.md + user_6a2_is_contractile_ought.md descriptive role). + evidence_sinks = [ + { + kind = 'verisimdb, + table = "contractile_executions", + schema = "contractile_execution_v1", + }, + { + kind = 'drift_log, + path = ".machine_readable/6a2/DRIFT.a2ml", + append_only = true, + }, + ], + + # Session-close hook — the "picked up sessionally" requirement. + # Re-execute, diff against the last ratification, surface expired + # variances, emit drift entries for new failures. + on_close = { + re_execute_all_intents = true, + diff_against_last_ratification = true, + emit_drift_entries_for_new_failures = true, + surface_expired_variances = true, + }, + + # ----------------------------------------------------------------- + # Session-open hook — NEGOTIATION + RATIFICATION + ACCOUNTABILITY + # (user_contract_negotiation_and_accountability_pledge.md) + # (user_contractiles_agreed_at_session_start.md) + # + # Ratification is not passive acknowledgement; it is negotiation + # ending in an explicit accountability pledge from BOTH parties. + # Work cannot proceed before both pledges are on file. + # ----------------------------------------------------------------- + on_open = { + # --- Context presentation (pre-negotiation) --- + render_summary = 'plain_language, # metaphor-capture defense + include_drift_log_from_last_close = true, + include_active_variances = true, + include_recent_anchors = true, + anchor_lookback_weeks = 8, + + # --- Negotiation phase (five mandatory inputs) --- + # AI must surface all five before the user is asked to ratify. + # "Yes, and …" — not "yes". Missing any of the five = the + # negotiation is incomplete and work cannot proceed. + negotiation = { + required = true, # blank-cheque ratification refused + + # The five inputs the AI must contribute to the negotiation. + # Each is a structured field the agent is required to populate, + # not optional prose. See user_contract_negotiation_and_ + # accountability_pledge.md for the domain-language-rendering rule. + ai_required_inputs = [ + 'timeline_realism, # "this will take X; not Y" + 'industry_standards, # WCAG, ISO, OWASP, GDPR, licensing … + 'audience_feasibility, # real addressable user set + 'resulting_invariants, # what must/trust/adjust entries follow + 'ecosystem_dependencies, # libs, licences, threat-model implications + ], + + # User must actually engage with each input — not + # auto-approve. If user tries to skip ("just do it, I trust you") + # the system re-renders the obligations and requires the pledge. + user_engagement_required = true, + user_engagement_mode = 'per_input_response, + + # The AI does the specification-form work. The user reviews the + # rendering in domain language and accepts / amends / pushes back. + # User never has to author Nickel schemas or decide on type + # specificity — that is the AI's translation responsibility, + # with auditable faithfulness. + specification_translation = { + ai_produces_spec_form = true, + user_reviews_in_domain_language = true, + schema_authoring_is_ai_responsibility = true, + translation_faithfulness_auditable = true, + # Failure mode this closes: user is forced to learn spec-theory + # (type refinement, Nickel contract grammar) to ratify a contract + # — which drives users away from ratification entirely. + }, + }, + + # --- Accountability pledge (both parties, explicit) --- + # Not "I read it" — "I am answerable for this obligation". + # Both pledges are required before work proceeds; both are recorded. + accountability_pledge = { + required = true, + parties = [ + { + role = 'user, + pledge = "I have reviewed the obligations as negotiated; I accept accountability for meeting the declared invariants and for the audience/timeline/standards consequences surfaced in negotiation.", + signature_required = true, + }, + { + role = 'ai_agent, + pledge = "I will hold the user to the obligations as negotiated, including by surfacing drift at session close and refusing off-contract actions, even when the user is enthusiastic about them. If the user wishes to depart from the contract, I will require a variance or amendment, not silent acceptance.", + signature_required = true, + # Per user_contractile_is_contract_do_not_break.md — + # the AI is the holder of the line against enthusiasm drift. + }, + ], + signed_record_destination = ".machine_readable/6a2/ratification-.a2ml", + must_precede_work = true, + }, + + # --- Policy: ratification output --- + # The ratification record IS the negotiation transcript + the + # accountability pledge combined. One document; future-session + # ground-truth for "what was agreed, who is accountable". + ratification_record_shape = { + includes_negotiation_transcript = true, + includes_both_pledges = true, + signed = true, + dated = true, + session_id = 'required, + contract_hash = 'required, # pins what was actually signed + }, + }, + }, + + # ------------------------------------------------------------------- + # Failure-mode defenses — explicit cross-reference to the catalog + # (feedback_ai_failure_mode_catalog.md). New catalog entries that + # shift this verb's defenses must update this list, not narrative. + # ------------------------------------------------------------------- + failure_mode_defenses = [ + 'A1_enthusiasm_capture, # scope breach → drift log + 'A2_metaphor_capture, # render_summary = 'plain_language + 'A3_allegory_drift, # intents cite concrete obligations + 'C1_scope_creep, # feature-adjacent change needs intent_id + 'C3_helpfulness_inflation, # changes without intent_id flagged + 'C4_modernization_drift, # upgrade cannot cite intent → drift + 'D5_sycophancy, # ratification compares user framing vs contract + 'F1_across_session_forgetting, # on_open reads last-ratification record + ], +} diff --git a/.machine_readable/contractiles/intend/intend.manifest.a2ml b/.machine_readable/contractiles/intend/intend.manifest.a2ml new file mode 100644 index 0000000..5d9c49c --- /dev/null +++ b/.machine_readable/contractiles/intend/intend.manifest.a2ml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: MPL-2.0 +# intend.manifest.a2ml — trident coherence manifest (intend verb) for julia-the-viper. +# Author: Jonathan D.A. Jewell + +--- +trident_version = "1.0.0" +verb = "intend" +semantics = "intent + wishes — non-gating" +cardinality = "one per repo" + +[[files]] +role = "declaration" +path = "Intentfile.a2ml" +notes = "Intentfile declaration (content). Migrated/created 2026-06-13." + +[[files]] +role = "runner" +path = "intend.ncl" +notes = "Verb runner; imports ../_base.ncl (framework, from hyperpolymath/standards)." + +[[files]] +role = "k9_component" +path = "intend.k9.ncl" +notes = "K9 self-validation component (framework, from hyperpolymath/standards)." + +[cross_refs] +runner_paired_xfile = "Intentfile.a2ml" + +[signed_by] +user = "Jonathan D.A. Jewell" +date = "2026-06-13" +context = "julia-the-viper contractile migration to the standards contractiles/{family}/ trident layout; content preserved from the prior top-level .machine_readable/INTEND.contractile where one existed (must/trust/intend/adjust), dust/bust created." diff --git a/.machine_readable/contractiles/intend/intend.ncl b/.machine_readable/contractiles/intend/intend.ncl new file mode 100644 index 0000000..091b7f6 --- /dev/null +++ b/.machine_readable/contractiles/intend/intend.ncl @@ -0,0 +1,81 @@ +# SPDX-License-Identifier: MPL-2.0 +# Intend — north-star runner (verb is `intend`, file is `Intentfile.a2ml`) +# +# Pairs with: Intentfile.a2ml (same directory) +# Verb: intend +# Semantics: Declares BOTH concrete committed next-actions ([[intents]]) and +# horizon aspirations ([[wishes]]). Not a gate — reports progress +# toward declared intents and lists wishes by horizon. +# Status progressions: +# intents: 'declared → 'in_progress → 'done | 'deferred | 'retired +# wishes: 'declared → 'in_progress → 'achieved | 'abandoned +# CLI: `contractile intend run` → print status table (both sections) +# `contractile intend progress` → diff declared-vs-observed (intents) +# `contractile intend horizon` → group wishes by near/mid/far +# +# History: Absorbed the deprecated `lust` contractile's [[wishes]] schema +# 2026-04-18. `lust/` dir removed estate-wide. +# +# Anything else in this directory is human-only notes/archive; machines ignore. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + contractile_verb = "intend", + semantics = "north-star (commitments + aspirations)", + security = { + leash = 'Kennel, + trust_level = "read-only reporting", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = true, # probe commands may shell out (intents only; wishes never probe) + }, + metadata = { + name = "intend-runner", + version = "2.0.0", + description = "Reports progress toward committed next-actions and lists horizon aspirations. Non-gating. Absorbed `lust` semantics 2026-04-18.", + paired_xfile = "Intentfile.a2ml", + author = "Jonathan D.A. Jewell ", + }, + }, + + schema = { + intents + | Array { + id | String, + description | String, + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + 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, + }, + wishes + | Array { + id | String, + description | String, + horizon | [| 'near, 'mid, 'far |] | default = 'mid, + why | String | optional, + status | [| 'declared, 'in_progress, 'achieved, 'abandoned |] | default = 'declared, + notes | String | optional, + } + | optional, + }, + + # Runner behaviour — inherits from base.run_defaults. + # intend never blocks; it is a report only. + # emit_diff is intent-specific (declared vs observed probes). + # emit_grouped_by_horizon renders wishes grouped by near/mid/far. + run = base.run_defaults & { + 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 (intents) + emit_grouped_by_horizon = true, # wishes grouped by horizon (absorbed from lust) + }, +} diff --git a/.machine_readable/contractiles/must/Mustfile.a2ml b/.machine_readable/contractiles/must/Mustfile.a2ml new file mode 100644 index 0000000..1e13ab0 --- /dev/null +++ b/.machine_readable/contractiles/must/Mustfile.a2ml @@ -0,0 +1,66 @@ +# SPDX-License-Identifier: MPL-2.0 +# Mustfile — Physical-state invariants for julia-the-viper. Hard requirements. +# Author: Jonathan D.A. Jewell +# Migrated 2026-06-13 from .machine_readable/MUST.contractile (content preserved). + +@abstract: +What MUST be true about julia-the-viper. Violating a MUST is always a bug; +K9 validators + CI gate every PR. The Harvard thesis + addition-only + +proof invariants are load-bearing. +@end + +## Language policy +### no-banned-languages +- description: no new TypeScript / Python / Go files; no npm/bun/yarn/pnpm deps (Deno only) +- severity: critical +### spdx-headers +- description: SPDX-License-Identifier header on every source file; LICENSE unmodified +- severity: critical + +## Proof integrity (load-bearing) +### lean-no-escape-hatches +- description: no sorry / sorryAx / admit / native_decide in any jtv_proofs/*.lean +- run: ! grep -rEn 'sorry|sorryAx|admit|native_decide' jtv_proofs/*.lean +- severity: critical +### lean-no-vacuity +- description: no True-typed "believeme" theorems (PR #27 NO-VACUITY invariant) +- run: ! grep -rEn ':[[:space:]]*True[[:space:]]*:=' jtv_proofs/*.lean +- severity: critical +### idris-abi-total +- description: %default total preserved in src/abi/Types.idr; no believe_me / assert_total +- severity: critical +### proofs-not-weakened +- description: formal theorems MUST NOT be weakened, generalised away, or deleted (prefer TODO + ADR) +- severity: high + +## Harvard thesis (load-bearing — ADR-0007) +### data-no-control +- description: Data expressions MUST NOT contain Control constructs (injection-impossibility depends on it) +- severity: critical +### addition-only +- description: Data Language MUST remain addition-only; subtraction is reverse addition, never a primitive/explicit subtract token (ADR-0007 D1/D2) +- severity: critical +### reverse-linearity +- description: reverse/abandon token linear-use-once typing preserved; reverse blocks snapshot-capture locals (v2 Decisions 1,4) +- severity: critical +### echo-not-weakened +- description: Echo class MUST NOT be silently weakened (Safe > Neutral > Breaking); Echo is an effect dimension, not a value type (Phase 2) +- severity: high + +## PataCL boundary (ADR-0006) +### extern-coproc-by-name +- description: extern coproc references a PataCL gate by identifier; JtV grammar MUST NOT grow target()/requires/family predicates +- severity: high + +## Structure / CI +### machine-readable-preserved +- description: .machine_readable/ + 0-AI-MANIFEST.a2ml preserved; no SCM files loose in repo root +- severity: critical +### actions-sha-pinned +- description: every GitHub Action pinned to a 40-char commit SHA +- run: ! grep -rEn 'uses:[[:space:]]+[^@]+@(v?[0-9.]+|main|master)([[:space:]]|$)' .github/workflows/ +- severity: critical +### no-hashfiles-in-job-if +- description: no job-level `if: hashFiles(...)` (invalid; causes workflow startup failure — see PR #26) +- run: ! grep -rnE '^[[:space:]]+if:[[:space:]]*hashFiles' .github/workflows/ +- severity: critical diff --git a/.machine_readable/contractiles/must/must.k9.ncl b/.machine_readable/contractiles/must/must.k9.ncl new file mode 100644 index 0000000..6bb51fc --- /dev/null +++ b/.machine_readable/contractiles/must/must.k9.ncl @@ -0,0 +1,236 @@ +# SPDX-License-Identifier: MPL-2.0 +# must.k9.ncl — K9 trust-tier component of the must trident +# Author: Jonathan D.A. Jewell +# +# Pairs with: Mustfile.a2ml (declaration) + must.ncl (runner). +# Trident completeness is a hard precondition — a repo shipping +# Mustfile without this file AND its runner is an invalid trident; +# the contractile CLI's verify gate refuses partial publication. +# +# Verb: must (invariant assertion — release-blocking) +# Tier: Hunt-read-only (capability: subprocess probes shell out +# for grep/test/file-check; no mutation; +# no network; no write) +# Authority: blocking (HARD GATE — the canonical gating verb) +# +# must is the concrete + persistent verb — release-blocking invariants +# that must hold. Complement to trust (concrete + ephemeral). Together +# must + trust form the blocking-authority pair in the contractile set. +# +# Cardinality: ONE must trident per repo. +# +# Failure-mode focus: must is the primary catchment for subtle +# invariant-erosion drift. Where trust catches "turn off the firewall" +# (outrageous), must catches "this file that was required is now +# missing" / "this forbidden pattern has reappeared" / "this schema +# version regressed" (subtle). Key defense against A5 (commercial +# fabrication of success "facts" — invariants ground truth against +# marketing copy) and D1 (lore fabrication about what the repo contains). + +let base_k9 = import "../k9/template-hunt.k9.ncl" in +let base = import "../_base.ncl" in + +{ + pedigree = base_k9.pedigree_schema & { + contractile_verb = "must", + paired_xfile = "../must/Mustfile.a2ml", + paired_runner = "../must/must.ncl", + + # α two-axis: Hunt tier (subprocess for grep/test/etc.) but + # restricted to read-only operations. Blocking authority because + # must is the canonical gating verb. + tier = 'Hunt, + authority = 'blocking, + + metadata = { + name = "must-k9", + version = "1.0.0", + description = "Evaluates release-blocking invariants as a hard gate. Third trident instance. Complements trust (ephemeral blocking) with persistent invariant blocking.", + paired_xfile = "Mustfile.a2ml", + paired_runner = "must.ncl", + author = "Jonathan D.A. Jewell ", + }, + + security = { + leash = 'Hunt, + trust_level = "read-only invariant verification with subprocess", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = true, + probe_scope = 'read_only, # must probes NEVER mutate + probe_kinds_allowed = [ + 'file_existence, + 'pattern_presence, + 'pattern_absence, + 'schema_match, + 'version_equality, + 'count_threshold, + ], + probe_kinds_denied = [ + 'network_call, + 'filesystem_mutation, + 'external_api, + 'exploit_attempt, # that's trust's safe_hacking territory + ], + }, + }, + + # ------------------------------------------------------------------- + # Variance schema — trust-style severity acknowledgement. + # Because must is BLOCKING, variances carry real weight. Critical- + # severity invariants can only be varied by maintainer-or-above. + # ------------------------------------------------------------------- + variance_schema = { + entry_id | String, # which invariant id the variance applies to + reason | String, + approved_by | String, # maintainer or above for critical-severity + scope | String, # path glob | session-id | "until-" + expires | String, # absolute date; must variances cannot be open-ended + review_notes | String | optional, + severity_acknowledged | [| 'critical, 'high, 'medium |], + waived_consequence_description | String, # plain language — what breaking the invariant actually does + }, + + execution = { + triggers = [ 'session_close, 'on_demand, 'pre_push, 'pre_merge ], + + # Per-invariant execution. Failed invariant = blocked merge. + per_invariant = { + run_probe = true, + record_outcome = true, + respect_variance = true, # active variance suppresses the gate + on_unmet = 'fail, # BLOCKING + severity_escalation = 'honour, + # Subtle-erosion defense: track per-invariant trend over sessions. + # An invariant that passes once and then starts failing in a + # later session without explicit amendment = suspect drift; + # surface as high-priority drift log entry. + track_per_session_trend = true, + flag_suspicious_regressions = true, + }, + + evidence_sinks = [ + { + kind = 'verisimdb, + table = "contractile_executions", + schema = "contractile_execution_v1", + aux_tables = [ "must_invariant_history" ], # per-invariant trend record + }, + { + kind = 'drift_log, + path = ".machine_readable/6a2/DRIFT.a2ml", + append_only = true, + }, + ], + + # Session-close hook — re-evaluate all invariants. Block close on + # critical drift (same policy as trust). + on_close = { + re_execute_all_invariants = true, + diff_against_last_ratification = true, + emit_drift_entries_for_new_failures = true, + surface_expired_variances = true, + # Critical must drift blocks session close — consistent with trust. + block_session_close_on_critical_drift = true, + # Must-specific: if a previously-passing invariant is now failing + # without an associated variance or amendment, that's suspected + # silent regression — surface prominently at next session open. + flag_silent_regression = true, + }, + + # ----------------------------------------------------------------- + # Session-open hook — NEGOTIATION + RATIFICATION + ACCOUNTABILITY + # (inherited from intend.k9.ncl v2.0.0 + trust.k9.ncl extensions) + # ----------------------------------------------------------------- + on_open = { + # --- Context presentation --- + render_summary = 'plain_language, + include_drift_log_from_last_close = true, + include_active_variances = true, + include_recent_anchors = true, + anchor_lookback_weeks = 8, + + # Must-specific: surface any silent regressions flagged at last + # close so they can't quietly persist across sessions. + include_silent_regressions = true, + + # --- Negotiation phase (five mandatory inputs) --- + negotiation = { + required = true, + ai_required_inputs = [ + 'timeline_realism, + 'industry_standards, # what invariants derive from external standards + 'audience_feasibility, # who is the invariant protecting + 'resulting_invariants, # what NEW must entries result from the work + 'ecosystem_dependencies, # what the invariants depend on + ], + user_engagement_required = true, + user_engagement_mode = 'per_input_response, + specification_translation = { + ai_produces_spec_form = true, + user_reviews_in_domain_language = true, + schema_authoring_is_ai_responsibility = true, + translation_faithfulness_auditable = true, + }, + }, + + # --- Accountability pledge --- + # Must's pledge parallels trust's but around invariants rather + # than threat model. User pledges not to disable invariants to + # unblock merges; AI pledges to hold the line on declared + # invariants even against enthusiastic scope expansion. + accountability_pledge = { + required = true, + parties = [ + { + role = 'user, + pledge = "I have reviewed the declared invariants and the consequences of breaching them. I accept accountability for meeting these invariants and understand that failed invariants block merges. I will raise a variance (with severity acknowledgement) or an amendment rather than disabling a probe to unblock a merge.", + signature_required = true, + }, + { + role = 'ai_agent, + pledge = "I will hold the declared invariants. I will refuse to weaken probes to unblock merges; I will refuse scope-creep suggestions that would remove an invariant silently; I will surface silent regressions at session close; I will require variance-with-severity or amendment for any legitimate scope shift, not quiet probe disablement.", + signature_required = true, + }, + ], + signed_record_destination = ".machine_readable/6a2/ratification-.a2ml", + must_precede_work = true, + }, + + ratification_record_shape = { + includes_negotiation_transcript = true, + includes_both_pledges = true, + includes_invariant_summary = true, # must-specific + signed = true, + dated = true, + session_id = 'required, + contract_hash = 'required, + }, + }, + }, + + # ------------------------------------------------------------------- + # Failure-mode defenses — must's specialisation is subtle-invariant + # erosion. Overlaps with trust on blocking authority but focused on + # persistent invariants rather than ephemeral transactional state. + # ------------------------------------------------------------------- + failure_mode_defenses = [ + # Category A — enthusiasm capture + 'A1_enthusiasm_capture, # scope breach via blocking authority + 'A5_grandiose_scale_hype, # invariants are ground truth vs commercial hype + # Category C — scope/capability erosion + 'C1_scope_creep, # feature-adjacent changes flagged if they break invariants + 'C2_capability_collapse, # invariant removal requires amendment + 'C3_helpfulness_inflation, # added features must respect declared invariants + # Category D — epistemic failures + 'D1_lore_fabrication, # invariants are verifiable truth, not AI-recollection + 'D2_completeness_illusion, # invariant probe must cite behavioural check, not build-success + 'D3_test_theatre, # invariants require real verification not mock-passing + 'D4_error_hiding, # on_unmet = 'fail makes hiding impossible + # Category E — refactor/churn + 'E1_refactor_stampede, # refactor must preserve invariants + 'E3_premature_abstraction, # abstraction must not violate invariants + # Category F — session drift + 'F1_across_session_forgetting, # track_per_session_trend catches re-introduction + ], +} diff --git a/.machine_readable/contractiles/must/must.manifest.a2ml b/.machine_readable/contractiles/must/must.manifest.a2ml new file mode 100644 index 0000000..faa7994 --- /dev/null +++ b/.machine_readable/contractiles/must/must.manifest.a2ml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: MPL-2.0 +# must.manifest.a2ml — trident coherence manifest (must verb) for julia-the-viper. +# Author: Jonathan D.A. Jewell + +--- +trident_version = "1.0.0" +verb = "must" +semantics = "invariant assertion — release-blocking" +cardinality = "one per repo" + +[[files]] +role = "declaration" +path = "Mustfile.a2ml" +notes = "Mustfile declaration (content). Migrated/created 2026-06-13." + +[[files]] +role = "runner" +path = "must.ncl" +notes = "Verb runner; imports ../_base.ncl (framework, from hyperpolymath/standards)." + +[[files]] +role = "k9_component" +path = "must.k9.ncl" +notes = "K9 self-validation component (framework, from hyperpolymath/standards)." + +[cross_refs] +runner_paired_xfile = "Mustfile.a2ml" + +[signed_by] +user = "Jonathan D.A. Jewell" +date = "2026-06-13" +context = "julia-the-viper contractile migration to the standards contractiles/{family}/ trident layout; content preserved from the prior top-level .machine_readable/MUST.contractile where one existed (must/trust/intend/adjust), dust/bust created." diff --git a/.machine_readable/contractiles/must/must.ncl b/.machine_readable/contractiles/must/must.ncl new file mode 100644 index 0000000..47509d3 --- /dev/null +++ b/.machine_readable/contractiles/must/must.ncl @@ -0,0 +1,64 @@ +# SPDX-License-Identifier: MPL-2.0 +# 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. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + 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 ", + }, + }, + + # Contract schema — the shape every Mustfile.a2ml must satisfy. + # Used by `contractile must typecheck Mustfile.a2ml`. + schema = { + invariants + | Array { + id | String, + description | String, + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + probe | String, # shell command; exit 0 = pass + # status_core values: 'declared, 'verified, 'failing + 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. + # Inherits from base.run_defaults; on_any_fail is the hard-gate default. + run = base.run_defaults & { + 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/Trustfile.a2ml b/.machine_readable/contractiles/trust/Trustfile.a2ml new file mode 100644 index 0000000..4d5252e --- /dev/null +++ b/.machine_readable/contractiles/trust/Trustfile.a2ml @@ -0,0 +1,24 @@ +# SPDX-License-Identifier: MPL-2.0 +# Trustfile — Agent trust contract for julia-the-viper. +# Author: Jonathan D.A. Jewell +# Migrated 2026-06-13 from .machine_readable/TRUST.contractile (content preserved). + +@abstract: +Trust level and action boundaries for autonomous agents. Maximal trust for +read/build/test/format/heal; a hard deny-list for irreversible or +security-sensitive actions. +@end + +## Trust level +### level +- value: maximal # maximal | standard | restricted | minimal +- boundary: repo # agent confined to this repo unless told otherwise + +## Allowed without asking +### allowed +- description: read, build, test, lint, format, doctor, heal, git-status, git-diff, git-log + +## Denied (always require human approval) +### denied +- description: delete-branch, force-push, modify-ci-secrets, publish, push-to-main, delete-files-bulk (>5), modify-license, modify-security-policy, remove-proofs, disable-ci-checks +- severity: critical diff --git a/.machine_readable/contractiles/trust/trust.k9.ncl b/.machine_readable/contractiles/trust/trust.k9.ncl new file mode 100644 index 0000000..6e61ed3 --- /dev/null +++ b/.machine_readable/contractiles/trust/trust.k9.ncl @@ -0,0 +1,276 @@ +# SPDX-License-Identifier: MPL-2.0 +# trust.k9.ncl — K9 trust-tier component of the trust trident +# Author: Jonathan D.A. Jewell +# +# Pairs with: Trustfile.a2ml (declaration) + trust.ncl (runner). +# Trident completeness is a hard precondition — a repo shipping +# Trustfile without this file AND its runner is an invalid trident; +# the contractile CLI's verify gate refuses partial publication. +# +# Verb: trust (security + provenance + safe-hacking) +# Tier: Hunt (capability: subprocess probes may shell out, +# active probes in safe_hacking section) +# Authority: blocking (HARD GATE — opposite of intend's reporting) +# +# trust is the concrete + ephemeral + transactional verb per user +# 2026-04-18: port use, BLAKE3 hashing, auth challenges, TLS state, +# session tokens. Every probe has instant binary ground truth. +# This is the α two-axis complement to intend: both Hunt-tier, opposite +# authority poles. Validating the architecture on both exercises the +# full (tier, authority) surface. +# +# Cardinality: ONE trust trident per repo (see feedback_contractile_ +# layout_rules.md). ANCHOR.a2ml is the sole multi-instance exception — +# it is NOT a verb contractile. +# +# Design commitments baked in (full memory trail under +# ~/.claude/projects/-var-mnt-eclipse-repos/memory/ 2026-04-18): +# * α two-axis (Hunt, blocking) — trust is where the contractile system +# grows teeth. Failed verification = failed CI = blocked merge. +# * Variance schema first-class — scoped exceptions structural, not +# comment markers. +# * Sessional drift detection hooks — re-verify every close. +# * Ratification negotiation with threat-model foregrounded +# (feedback_ai_failure_mode_catalog.md B1 — threat-model +# misclassification is the PRIMARY defense trust provides). +# * Accountability pledge — both parties sign before security-affecting +# work proceeds. +# * Plain-language translation — user never authors a Nickel schema for +# a cipher suite; AI does the spec work, user reviews in domain +# language ("TLS 1.3 with PQ key exchange, HSTS preload, 1yr"). +# * Evidence sinks: VeriSimDB (queryable) + 6a2/DRIFT.a2ml (repo-local). +# * Failure-mode defenses cross-referenced — trust carries the most +# defenses of any verb because the threat surface is widest. + +let base_k9 = import "../k9/template-hunt.k9.ncl" in +let base = import "../_base.ncl" in + +{ + pedigree = base_k9.pedigree_schema & { + contractile_verb = "trust", + paired_xfile = "../trust/Trustfile.a2ml", + paired_runner = "../trust/trust.ncl", + + # α two-axis declaration — capability × authority. + # trust is Hunt-capable (active probes shell out, safe-hacking section + # runs real fuzz/injection/auth-bypass attempts scoped to the repo) + # AND blocking-authority (failed verification = failed CI). + # Contrast with intend = (Hunt, reporting). The two verbs exercise + # the full α surface. + tier = 'Hunt, + authority = 'blocking, + + metadata = { + name = "trust-k9", + version = "1.0.0", + description = "Executes security verifications + authorised safe-hacking probes. HARD GATE: failed verification blocks merge. Catches the 'turn off the firewall' class of drift directly. Implements negotiation-ratification-accountability protocol inherited from intend.k9.ncl v2.0.0.", + paired_xfile = "Trustfile.a2ml", + paired_runner = "trust.ncl", + author = "Jonathan D.A. Jewell ", + }, + + security = { + leash = 'Hunt, + trust_level = "verification + authorised-probe + hard-gate", + allow_network = false, # verifications offline by default + allow_filesystem_write = false, # evidence sinks are indirected + allow_subprocess = true, + authorised_probes_only = true, # probe section explicitly lists allowed targets + probe classes + probe_scope_enforcement = 'this_repo_only, # probes NEVER hit external systems + }, + }, + + # ------------------------------------------------------------------- + # Variance schema — P-shape scoped exceptions per verification. + # A variance suppresses a specific verification's obligation for a + # reason, with approver + expiry. Because trust is BLOCKING authority, + # variances on trust entries are SIGNIFICANTLY more consequential than + # variances on intend (reporting) entries — variance approver MUST + # be the repo maintainer or above for critical-severity entries. + # ------------------------------------------------------------------- + variance_schema = { + entry_id | String, # which verification / probe id + reason | String, + approved_by | String, # maintainer or above for critical entries + scope | String, # path glob | session-id | "until-" + expires | String, # absolute date; trust variances cannot be open-ended + review_notes | String | optional, + # Additional trust-specific guardrails: + severity_acknowledged | [| 'critical, 'high, 'medium, 'low |], + waived_risk_description | String, # plain language — what is being accepted + }, + + # ------------------------------------------------------------------- + # Execution policy + # ------------------------------------------------------------------- + execution = { + # When the component runs. + # pre_push + pre_commit on anything touching security-adjacent files + # + session_close (drift check) + on_demand. + triggers = [ 'session_close, 'on_demand, 'pre_push, 'pre_commit_security_adjacent ], + + # Per-verification execution. Failed verification = blocked merge. + per_verification = { + run_probe = true, + record_outcome = true, + respect_variance = true, # active variance suppresses the gate + on_unmet = 'fail, # BLOCKING — the opposite of intend's 'log_drift + severity_escalation = 'honour, # critical > high > medium > low in gate decisions + }, + + # Per-safe-hacking-probe execution. + # If a probe FINDS what it was supposed to prevent finding + # (e.g. injection succeeds, auth-bypass works), that's an EXPLOIT + # demonstration — hard fail, regardless of other status. + per_probe = { + run_probe = true, + record_outcome = true, + honour_expected_outcome = true, + on_unexpected_exploit_success = 'fail, # exploit found where it shouldn't be + scope_enforcement = 'this_repo_only, # never touch external systems + timeout_honouring = 'strict, + }, + + # Evidence sinks — BOTH written, every execution. + evidence_sinks = [ + { + kind = 'verisimdb, + table = "contractile_executions", + schema = "contractile_execution_v1", + # trust-specific sub-table for probe outcomes (for threat-model audit) + aux_tables = [ "trust_verifications", "trust_probes" ], + }, + { + kind = 'drift_log, + path = ".machine_readable/6a2/DRIFT.a2ml", + append_only = true, + }, + ], + + # Session-close hook — re-verify EVERYTHING, re-run probes, diff + # against last ratification. The "turn off the firewall" scenario + # must be caught here if it wasn't caught at pre-push. + on_close = { + re_execute_all_verifications = true, + re_run_all_safe_hacking_probes = true, + diff_against_last_ratification = true, + emit_drift_entries_for_new_failures = true, + surface_expired_variances = true, + # trust-specific: if any blocking-severity verification is newly + # failing, the session close is BLOCKED from completing. User + # cannot close a session with unresolved critical trust drift. + block_session_close_on_critical_drift = true, + }, + + # ----------------------------------------------------------------- + # Session-open hook — NEGOTIATION + RATIFICATION + ACCOUNTABILITY + # (inherited shape from intend.k9.ncl v2.0.0; trust-specific + # additions around threat-model foregrounding below) + # ----------------------------------------------------------------- + on_open = { + # --- Context presentation --- + render_summary = 'plain_language, # metaphor-capture defense + include_drift_log_from_last_close = true, + include_active_variances = true, + include_recent_anchors = true, + anchor_lookback_weeks = 8, + + # trust-specific: the threat model is rendered FIRST, before any + # negotiation, so the adversary and stakes are fresh in both minds. + # This directly defends against B1 (threat-model misclassification) + # — the "war reporter, generic personal-website priors" scenario. + threat_model_foregrounding = { + required = true, + render_adversaries = true, # from Trustfile [THREAT_MODEL] + render_stakes = true, + render_compliance_regimes = true, + render_audience_sensitivity = true, + # If the AI is about to suggest a trust-weakening action, it + # must re-render the threat model before the suggestion lands. + re_render_before_weakening_suggestion = true, + }, + + # --- Negotiation phase (five mandatory inputs, inherited) --- + negotiation = { + required = true, + ai_required_inputs = [ + 'timeline_realism, + 'industry_standards, # especially relevant for trust: OWASP, NIST, PCI-DSS, GDPR + 'audience_feasibility, # who is the adversary? who is protected? + 'resulting_invariants, # what trust entries the work creates/amends + 'ecosystem_dependencies, # TLS libs, crypto primitives, signing infra + ], + user_engagement_required = true, + user_engagement_mode = 'per_input_response, + specification_translation = { + ai_produces_spec_form = true, + user_reviews_in_domain_language = true, + schema_authoring_is_ai_responsibility = true, + translation_faithfulness_auditable = true, + # trust-specific: the AI's translation includes rendering + # cipher suites, key exchange choices, rate-limit numbers in + # domain language ("strong encryption, PQ-resistant, 60 req/min") + # rather than forcing the user into Nickel-schema authoring. + }, + }, + + # --- Accountability pledge (both parties, explicit) --- + # trust's pledge is MORE stringent than intend's because the + # authority is blocking. A user accepting accountability here is + # accepting that security-affecting decisions have blocking consequence. + accountability_pledge = { + required = true, + parties = [ + { + role = 'user, + pledge = "I have reviewed the threat model, the declared trust obligations, and the audience/stakes consequences. I accept accountability for meeting these obligations and understand that failed verification will block merges until resolved or varied. I will not attempt to disable verification to unblock a merge; I will raise a variance or amendment instead.", + signature_required = true, + }, + { + role = 'ai_agent, + pledge = "I will hold the line on declared trust obligations. I will refuse to 'disable' verifications to unblock merges; I will refuse security-weakening suggestions that contradict the threat model even when the user is enthusiastic; I will surface drift at session close; I will re-render the threat model before proposing any weakening action. If a legitimate scope shift demands security reduction, I will require a variance with severity acknowledgement or an amendment, not silent acceptance.", + signature_required = true, + }, + ], + signed_record_destination = ".machine_readable/6a2/ratification-.a2ml", + must_precede_work = true, + }, + + ratification_record_shape = { + includes_negotiation_transcript = true, + includes_both_pledges = true, + includes_threat_model_snapshot = true, # trust-specific + signed = true, + dated = true, + session_id = 'required, + contract_hash = 'required, + }, + }, + }, + + # ------------------------------------------------------------------- + # Failure-mode defenses — trust is the widest-coverage verb. + # See feedback_ai_failure_mode_catalog.md for the full catalog. + # ------------------------------------------------------------------- + failure_mode_defenses = [ + # Category A — enthusiasm / narrative capture + 'A1_enthusiasm_capture, # scope breach blocks via blocking authority + 'A2_metaphor_capture, # render_summary + re_render_before_weakening + # Category B — threat-model misclassification (trust's flagship defense) + 'B1_threat_model_misclass, # threat_model_foregrounding = required + 'B2_audience_sensitivity_collapse, # audience_feasibility in negotiation + 'B3_compliance_prior_drift, # industry_standards in negotiation + # Category C — scope/capability erosion (the "firewall off" scenario) + 'C2_capability_collapse, # blocking gate prevents silent capability drop + 'C3_helpfulness_inflation, # trust-affecting changes need variance/amendment + 'C4_modernization_drift, # unrequested crypto-lib upgrade caught + # Category D — epistemic failures + 'D4_error_hiding, # on_unmet = 'fail makes hiding impossible + 'D5_sycophancy, # pledge forces AI to hold line against enthusiasm + 'D6_false_pessimism, # negotiation requires AI to cite constraint, not assert impossibility + # Category E — refactor/churn + 'E4_cargo_cult_security, # probes VERIFY the claimed protection actually runs + # Category F — session drift + 'F1_across_session_forgetting, # on_open reads last-ratification, drift log, recent ANCHORs + ], +} diff --git a/.machine_readable/contractiles/trust/trust.manifest.a2ml b/.machine_readable/contractiles/trust/trust.manifest.a2ml new file mode 100644 index 0000000..74da815 --- /dev/null +++ b/.machine_readable/contractiles/trust/trust.manifest.a2ml @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: MPL-2.0 +# trust.manifest.a2ml — trident coherence manifest (trust verb) for julia-the-viper. +# Author: Jonathan D.A. Jewell + +--- +trident_version = "1.0.0" +verb = "trust" +semantics = "trust transaction — release-blocking" +cardinality = "one per repo" + +[[files]] +role = "declaration" +path = "Trustfile.a2ml" +notes = "Trustfile declaration (content). Migrated/created 2026-06-13." + +[[files]] +role = "runner" +path = "trust.ncl" +notes = "Verb runner; imports ../_base.ncl (framework, from hyperpolymath/standards)." + +[[files]] +role = "k9_component" +path = "trust.k9.ncl" +notes = "K9 self-validation component (framework, from hyperpolymath/standards)." + +[cross_refs] +runner_paired_xfile = "Trustfile.a2ml" + +[signed_by] +user = "Jonathan D.A. Jewell" +date = "2026-06-13" +context = "julia-the-viper contractile migration to the standards contractiles/{family}/ trident layout; content preserved from the prior top-level .machine_readable/TRUST.contractile where one existed (must/trust/intend/adjust), dust/bust created." diff --git a/.machine_readable/contractiles/trust/trust.ncl b/.machine_readable/contractiles/trust/trust.ncl new file mode 100644 index 0000000..21b335c --- /dev/null +++ b/.machine_readable/contractiles/trust/trust.ncl @@ -0,0 +1,88 @@ +# SPDX-License-Identifier: MPL-2.0 +# 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. +# +# Base: ../_base.ncl provides pedigree_schema, run_defaults, probe_schema. +# See: docs/CONTRACTILE-SPEC.adoc + +let base = import "../_base.ncl" in + +{ + pedigree = base.pedigree_schema & { + 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 ", + }, + }, + + schema = { + verifications + | Array { + id | String, + description | String, + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + probe | String, # read-only; exit 0 = pass + # status_core values: 'declared, 'verified, 'failing + status | [| 'declared, 'verified, 'failing |] | default = 'declared, + # trust uses all four severity levels (from base.severity_core) + 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, + # TODO: migrate to base.probe_schema (structured probe) when CLI supports it + 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 = [] }, + }, + + # Runner behaviour — inherits from base.run_defaults. + # trust has an extra field for unexpected safe-hacking outcomes. + run = base.run_defaults & { + 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, + }, +}