diff --git a/.machine_readable/ADJUST.contractile b/.machine_readable/ADJUST.contractile deleted file mode 100644 index 1d169c1..0000000 --- a/.machine_readable/ADJUST.contractile +++ /dev/null @@ -1,126 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; ADJUST.contractile — Accessibility invariants for julia-the-viper -; "ADJUST" = Accessibility & Digital Justice for Universal Software & Technology -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST -; This file is machine-readable. LLM/SLM agents MUST NOT violate these invariants. - -; ── Definitions ────────────────────────────────────────────────── -; -; ADJUST (noun/verb) -; The accessibility contractile. Defines how software must adapt to serve -; all users regardless of ability, device, or context. Named for the verb -; "adjust" — to make suitable, to adapt, to accommodate — which is the -; core action of accessible design. -; -; Scope: -; ADJUST governs all user-facing interfaces: GUI, TUI, CLI, web, mobile, -; documentation, error messages, and installation flows. It applies to -; both human users and assistive technologies (screen readers, switch -; devices, braille displays, voice control). -; -; Relationship to other contractiles: -; - MUST: ADJUST invariants are a subset of MUST — violating ADJUST -; is a MUST violation. ADJUST exists separately because accessibility -; rules are numerous enough to warrant their own file, and because -; LLMs frequently forget accessibility unless explicitly reminded. -; - TRUST: ADJUST does not affect trust levels. All trust tiers must -; respect ADJUST invariants equally. -; - DUST: Deprecating a feature does not exempt it from ADJUST until -; it is fully removed. Deprecated UI must remain accessible. -; - INTENT: ADJUST supports the anti-purpose "this software is NOT -; only for able-bodied users with modern hardware." -; -; Standard: WCAG 2.2 Level AA (minimum) -; https://www.w3.org/WAI/WCAG22/quickref/?levels=aaa -; -; Why a separate file: -; Experience shows LLMs and developers alike treat accessibility as an -; afterthought. By placing invariants in a contractile that is loaded -; at session start, we make it structurally impossible to forget. -; -; ── End Definitions ────────────────────────────────────────────── - -(adjust-contractile - (version "1.0.0") - (full-name "Accessibility & Digital Justice for Universal Software & Technology") - (standard "WCAG-2.2-AA") - (repo "julia-the-viper") - - (invariants - ; ── Visual ── - (adjust "colour-contrast-ratio >= 4.5:1 for normal text") - (adjust "colour-contrast-ratio >= 3:1 for large text (18pt+ or 14pt+ bold)") - (adjust "no information conveyed by colour alone") - (adjust "no flashing or strobing content (3 flashes/second max)") - (adjust "text resizable to 200% without loss of content or function") - (adjust "focus indicators visible on all interactive elements") - - ; ── Keyboard ── - (adjust "all interactive elements reachable via keyboard (Tab/Shift+Tab)") - (adjust "no keyboard traps — user can always Tab away") - (adjust "skip navigation link present on pages with repeated blocks") - (adjust "logical focus order follows visual reading order") - - ; ── Screen reader ── - (adjust "all images have meaningful alt text (or alt='' if decorative)") - (adjust "all form inputs have associated labels") - (adjust "ARIA landmarks used for page regions (main, nav, banner, etc.)") - (adjust "dynamic content updates announced via aria-live regions") - (adjust "semantic HTML used (headings, lists, tables) — not div soup") - - ; ── Interactive ── - (adjust "touch targets minimum 44x44px on mobile/touch interfaces") - (adjust "error messages identify the field and describe the error") - (adjust "error messages not conveyed by colour or position alone") - (adjust "form validation provides suggestions for correction") - - ; ── Media ── - (adjust "video has captions (closed or open)") - (adjust "audio-only content has text transcript") - (adjust "no autoplay of media with sound") - - ; ── Motion ── - (adjust "animations respect prefers-reduced-motion media query") - (adjust "no content depends on motion to convey meaning") - - ; ── CLI/TUI ── - (adjust "CLI output must not rely solely on colour (use symbols: [OK] [FAIL])") - (adjust "TUI must support high-contrast mode") - (adjust "all CLI commands support --help with plain-text output") - (adjust "error messages written in plain language, not jargon or codes alone") - - ; ── Documentation ── - (adjust "docs use clear language, short sentences, logical structure") - (adjust "code examples include comments explaining non-obvious steps") - (adjust "diagrams have text descriptions or alt text") - - ; ── Internationalisation (i18n) ── - (adjust "all user-facing strings externalisable for translation") - (adjust "no hardcoded English in error messages — use message keys") - (adjust "date/time/number formats locale-aware") - (adjust "RTL (right-to-left) layout support where applicable") - (adjust "Unicode handled correctly throughout (UTF-8 everywhere)") - ) - - (related-resources - ; LOL — super-parallel corpus crawler for 1500+ languages - ; Use for linguistic data, translation coverage, and i18n validation - (lol "standards/lol — multilingual NLP corpus, see README.adoc") - (polyglot-i18n "polyglot-i18n — i18n framework and WASM translation engine") - ) - - (enforcement - (ci "accessibility linting in quality.yml workflow") - (pr-block "PR blocked if accessibility regression detected") - (tool "axe-core or pa11y for automated checks on web UI") - (tool "CLI output inspected for colour-only signalling") - (manual "manual screen reader test before major releases") - ) - - (notes - "These are MINIMUM requirements. Exceeding them (AAA) is encouraged." - "When in doubt about an accessibility decision, ask — don't guess." - "Accessibility is not optional polish — it is a structural requirement." - ) -) diff --git a/.machine_readable/INTENT.contractile b/.machine_readable/INTENT.contractile deleted file mode 100644 index a6b67c7..0000000 --- a/.machine_readable/INTENT.contractile +++ /dev/null @@ -1,104 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; INTENT.contractile — Purpose and scope for julia-the-viper -; Helps LLM/SLM agents understand what this repo IS and IS NOT. -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST - -; ── Definitions ────────────────────────────────────────────────── -; -; INTENT (noun) -; The purpose contractile. Defines what this repository IS, what it is -; NOT (anti-purpose), and which architectural decisions are load-bearing. -; Without INTENT, LLMs drift into scope creep, reverse key decisions, -; or add features that belong in a different repo. -; -; Scope: -; INTENT governs the conceptual boundaries of the project — its reason -; for existing, its domain, and its relationship to the ecosystem. -; It does NOT specify implementation details (that's MUST and code). -; -; Relationship to other contractiles: -; - MUST: INTENT explains WHY certain MUSTs exist. If you don't -; understand a MUST, read INTENT first. -; - TRUST: The "ask-before-touching" section in INTENT maps directly -; to TRUST.trust-deny for the most sensitive areas. -; - ADJUST: INTENT's anti-purpose should include "this software is -; NOT only for users with perfect vision/hearing/mobility." -; - DUST: When INTENT changes (repo pivots), related DUST entries -; should be created for the abandoned direction. -; -; ── End Definitions ────────────────────────────────────────────── - -(intent-contractile - (version "1.2.0") - (repo "julia-the-viper") - (last-updated "2026-06-02") - - ; === Purpose (what this repo IS) === - (purpose - "Julia the Viper (JtV) is a Harvard-architecture programming language that - grammatically separates Control (Turing-complete, imperative, effectful) from - Data (total, addition-only, provably halting). Its mission is to serve as a - universal extender: a language that can retrofit code-injection-resistant - semantics onto legacy systems (Python/PHP/JS) by making injection - grammatically impossible, not just a runtime check. v2 adds reversibility - via reverse blocks for quantum-simulation and Landauer-efficient computation. - Post-pivot 2026-04-19: compile-time decisions (target gating, feature gating, - coprocessor declaration liveness) are DELEGATED to PataCL — a sibling - language at /var/mnt/eclipse/repos/patacl/. - Echo type system (Phase 2, 2026-06-02): effect dimension tracking retained-loss - lineage; EchoSafe/EchoNeutral/EchoBreaking; @echo annotations at boundaries; - mechanised in JtvEcho.lean (Lean 4, zero sorry)." - ) - - ; === Anti-Purpose (what this repo is NOT — prevents scope creep) === - (anti-purpose - "JtV is NOT a general-purpose language — it is a grammatically-constrained - security-first language. It does NOT aim to be ergonomic at the expense - of the Harvard thesis. It does NOT grow a compile-time decision language - embedded in its own grammar — that work lives in PataCL (see - docs/design-decisions/0006-patacl-pivot.adoc). It does NOT claim Turing - completeness for Data expressions (that would break totality). It does - NOT attempt to replace Rust, Zig, or Ada — it coexists with them via - FFI and extern-coproc integration. It is NOT only for able-bodied users - with modern hardware — accessibility is a first-class concern - (see ADJUST.contractile)." - ) - - ; === Key Architectural Decisions That Must Not Be Reversed === - (architectural-invariants - ("Harvard separation — Control and Data are grammatically disjoint sublanguages; Data expressions cannot contain Control constructs. This is the load-bearing security thesis.") - ("Addition-only Data Language — the Data sublanguage uses addition as its sole binary operator; subtraction is syntactically forbidden. v2 reversibility uses auto-generated -= inside reverse blocks, but no explicit subtract token exists in user syntax.") - ("Totality — Data expressions provably halt by construction. @total / @pure / impure purity lattice enforces it.") - ("Injection-impossibility by grammar — attacker-controlled data cannot become executable control flow because Data grammar rejects Control constructs structurally.") - ("v2 reversibility via reverse blocks — snapshot-based rollback, linear ReversalToken typing, no new subtract syntax.") - ("Compile-time decisions delegated to PataCL — JtV gains one new construct (extern coproc { item* }) and references PataCL gates by name, never embeds predicate syntax. See ADR-0006.") - ("Idris2 for ABI when safety-critical paths land — dependent types prove FFI interface correctness.") - ("Zig for FFI emission — zero-cost C-ABI compatibility; @Vector for SIMD, asm volatile for custom opcodes.") - ("SPARK-optional for safety-critical coprocessors — formal contracts across the coproc boundary.") - ) - - ; === Sensitive Areas (if in doubt, ask) === - (ask-before-touching - "spec/LANGUAGE_SPECIFICATION.md — the published thesis; any change must preserve Harvard + totality claims" - "spec/grammar.ebnf — grammar spec; changes propagate to crates/jtv-core/src/grammar.pest" - "crates/jtv-core/src/grammar.pest — canonical parser grammar" - "docs/design-decisions/0001-0006-*.adoc — coprocessor / pata pathway ADR trail; ADR-0006 is current truth for the Delta pivot" - "docs/language/DESIGN-JTV-V2-REVERSIBILITY.md — v2 reversibility design (5 closed decisions)" - ".machine_readable/COPROC-TRAJECTORIES.a2ml — authoritative trajectory state; update via ADR process" - ".machine_readable/6a2/*.a2ml — descriptive state snapshot; update-all-six-together convention" - ) - - ; === Ecosystem Position === - (ecosystem - (belongs-to "standalone top-level repo") - (depends-on - ("PataCL (post-pivot 2026-04-19) — compile-time decision substrate for extern coproc blocks; located at /var/mnt/eclipse/repos/patacl/" - "Rust toolchain — current implementation language" - "pest / pest_derive — parser generator")) - (depended-on-by - ("(none yet; potentially future security-research adopters, legacy-retrofit users, or teaching/research use)")) - (first-adopter-of "PataCL — JtV is the first host-language adopter and co-designed the integration contract") - (sibling-languages "oblibeny (MPR heritage for PataCL); affinescript, my-lang (hyperpolymath language family)") - ) -) diff --git a/.machine_readable/MUST.contractile b/.machine_readable/MUST.contractile deleted file mode 100644 index 6710e8a..0000000 --- a/.machine_readable/MUST.contractile +++ /dev/null @@ -1,124 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; MUST.contractile — Baseline invariants for julia-the-viper -; These constraints MUST NOT be violated. K9 validators enforce them. -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST - -; ── Definitions ────────────────────────────────────────────────── -; -; MUST (noun/verb) -; The hard-constraint contractile. Defines invariants that are structurally -; required for the repository to function correctly and safely. Violating -; a MUST is always a bug — there are no "soft" MUSTs. -; -; Scope: -; MUST governs code, configuration, CI, and structure. It does NOT govern -; style, preference, or approach — those belong in CLAUDE.md or coding -; standards. MUST is for things that break the project if violated. -; -; Relationship to other contractiles: -; - TRUST: MUST is enforced regardless of trust level. Even maximal-trust -; agents cannot violate MUST constraints. -; - ADJUST: All ADJUST invariants are implicitly MUST invariants too. -; ADJUST exists separately for visibility. -; - INTENT: MUST protects the architectural decisions described in INTENT. -; - DUST: When a feature enters DUST (deprecation), its MUST constraints -; remain active until the feature is fully removed. -; -; Enforcement: -; K9 validators in contractiles/k9/ machine-check MUST constraints. -; CI runs these on every PR. Violations block merge. -; -; ── End Definitions ────────────────────────────────────────────── - -(must-contractile - (version "1.1.0") - (repo "julia-the-viper") - - ; === Universal Invariants (apply to ALL repos) === - - (invariants - ; Paths - (must "no hardcoded absolute paths (/home/*, /mnt/*, /var/mnt/*)") - (must "all paths use env vars, XDG dirs, or relative references") - - ; Language policy - (must "no new TypeScript files") - (must "no new Python files") - (must "no new Go files") - (must "no npm/bun/yarn/pnpm dependencies — Deno only") - - ; Dangerous patterns - (must "no believe_me (Idris2)") - (must "no assert_total (Idris2)") - (must "no Admitted (Coq)") - (must "no sorry (Lean)") - (must "no unsafeCoerce (Haskell)") - (must "no Obj.magic (OCaml)") - (must "no unsafe {} blocks without safety comment (Rust)") - - ; License - (must "SPDX-License-Identifier header on every source file") - (must "no removal or modification of LICENSE file") - - ; Structure - (must ".machine_readable/ directory preserved") - (must "0-AI-MANIFEST.a2ml preserved") - (must "no SCM files in repo root — only in .machine_readable/") - - ; CI - (must "no removal of CI workflows without explicit approval") - (must "all GitHub Actions SHA-pinned") - - ; Code quality - (must "tests must not be deleted or weakened") - (must "generated code in generated/ directory only") - (must "no introduction of OWASP top 10 vulnerabilities") - - ; ABI/FFI (if applicable) - (must "no modification of ABI contracts without proof update") - (must "no removal of formal verification proofs") - ) - - ; === Project-Specific Invariants (julia-the-viper) === - (project-invariants - ; Harvard thesis — LOAD-BEARING - (must "Data expressions MUST NOT contain Control constructs (if/while/for/assignment/print/impure calls) — grammatical injection-impossibility depends on this") - (must "Data Language MUST remain addition-only at syntax level — no explicit subtract token in user grammar") - (must "v2 reverse blocks MUST snapshot-capture locals on entry (Decision 1 in DESIGN-JTV-V2-REVERSIBILITY.md)") - (must "reverse tok / abandon tok linear-use-once typing MUST be preserved (v2 Decision 4)") - (must "Send to ExternalHandle inside reversible { } MUST be a static error unless wrapped in irreversible { } (v2 Decision 2)") - - ; Pata-pathway / PataCL integration (post-pivot 2026-04-19) - (must "extern coproc block MUST reference PataCL gate by identifier, not embedded predicate syntax (ADR-0006)") - (must "Compile-time decisions MUST be delegated to PataCL — JtV grammar MUST NOT grow target(...) / requires / family predicate operators") - (must "Extern coproc call sites MUST fire ExternCoprocNotYetLowered at evaluation when native lowering is not yet implemented (ADR-0005, informational phase-boundary error)") - (must "Encoding strings MUST remain opaque to JtV — assembler is authoritative (ADR-0005 Decision 7)") - - ; Purity lattice - (must "@pure functions MUST NOT contain loops or IO (v2 Pure Function enforcement)") - (must "@total functions MUST be provably terminating") - (must "Impure functions MUST NOT be callable from @pure contexts (Data context)") - - ; Echo type system (Phase 2 — 2026-06-02) - (must "Echo effect class MUST NOT be weakened without justification: Safe > Neutral > Breaking — a function that was Safe MUST NOT be silently reclassified Breaking") - (must "@echo(safe) annotations MUST only be applied to operations where bijectivity can be verified by the compiler") - (must "Echo is an effect dimension, NOT a value type — Echo value wrappers are reserved for Phase 4 and MUST NOT be introduced in Phase 2") - (must "Retained-loss lineage fibre (Sigma x, f x = y) is the authoritative Echo semantics — MUST NOT be replaced with a simpler 'some loss occurred' boolean") - - ; Formal proof invariants (2026-06-02) - (must "No sorry / sorryAx / admit / native_decide in any jtv_proofs/*.lean file") - (must "No believe_me / assert_total in src/abi/Types.idr") - (must "%default total MUST be preserved in src/abi/Types.idr") - (must "Lean proof libraries MUST compile under the pinned Lean version in jtv_proofs/lakefile.lean") - (must "Formal theorems MUST NOT be weakened, generalised away, or deleted — prefer marking as TODO with a follow-up ADR") - - ; Banned primitives (reinforces universal list) - (must "No Rust .unwrap() → .expect(\"TODO\") anti-pattern — equivalent panic with fake debt marker (per feedback_unwrap_to_expect_antipattern)") - ) - - (enforcement - (k9-validator "contractiles/k9/must-check.k9.ncl") - (ci "quality.yml runs must-check on every PR") - ) -) diff --git a/.machine_readable/TRUST.contractile b/.machine_readable/TRUST.contractile deleted file mode 100644 index 0c24057..0000000 --- a/.machine_readable/TRUST.contractile +++ /dev/null @@ -1,80 +0,0 @@ -; SPDX-License-Identifier: MPL-2.0 -; TRUST.contractile — Trust boundaries for julia-the-viper -; Defines what LLM/SLM agents are trusted to do without asking. -; -; Part of the contractile family: MUST, TRUST, DUST, INTENT, ADJUST - -; ── Definitions ────────────────────────────────────────────────── -; -; TRUST (noun/verb) -; The permission contractile. Defines the boundary between what an AI -; agent may do autonomously and what requires human approval. Trust is -; graduated — not binary — with four levels from minimal to maximal. -; -; Trust levels: -; - maximal: Agent may read, build, test, lint, format, heal freely. -; Only destructive/external actions require approval. -; - standard: Agent may read and build. Test/lint need approval. -; - restricted: Agent may read only. All modifications need approval. -; - minimal: Agent may read specific files only. Everything else blocked. -; -; Scope: -; TRUST governs AI agent behaviour only. It does not affect human -; contributors — humans follow CONTRIBUTING.md and GOVERNANCE.adoc. -; -; Relationship to other contractiles: -; - MUST: Trust never overrides MUST. Even at maximal trust, MUST -; violations are blocked. -; - ADJUST: Trust does not exempt from ADJUST. All trust tiers must -; produce accessible output. -; - INTENT: TRUST.trust-deny protects the sensitive areas listed in -; INTENT.ask-before-touching. -; - DUST: Deprecated features have the same trust rules as active ones. -; -; ── End Definitions ────────────────────────────────────────────── - -(trust-contractile - (version "1.0.0") - (repo "julia-the-viper") - - (trust-level "maximal") ; maximal | standard | restricted | minimal - - ; === Maximal Trust (default) === - ; LLM may freely do these without asking: - (trust-actions - "read" ; Read any file in the repo - "build" ; Run build commands - "test" ; Run test suites - "lint" ; Run linters and formatters - "format" ; Auto-format code - "doctor" ; Run self-diagnostics - "heal" ; Attempt automatic repair - "git-status" ; Check git status - "git-diff" ; View diffs - "git-log" ; View history - ) - - ; === Denied Actions (always require human approval) === - (trust-deny - "delete-branch" ; Could lose work - "force-push" ; Overwrites history - "modify-ci-secrets" ; Security sensitive - "publish" ; External visibility - "push-to-main" ; Protected branch - "delete-files-bulk" ; More than 5 files at once - "modify-license" ; Legal implications - "modify-security-policy" ; Security implications - "remove-proofs" ; Formal verification regression - "disable-ci-checks" ; Safety regression - ) - - ; === Trust Boundary === - (trust-boundary "repo") ; LLM confined to this repo unless explicitly told otherwise - - ; === Override === - ; Repos requiring tighter trust override these settings with justification: - ; (override - ; (trust-level "restricted") - ; (reason "Contains production secrets / handles PII / etc.") - ; ) -) diff --git a/.machine_readable/bot_directives/README.adoc b/.machine_readable/bot_directives/README.adoc new file mode 100644 index 0000000..af6a313 --- /dev/null +++ b/.machine_readable/bot_directives/README.adoc @@ -0,0 +1,35 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += Bot directives — julia-the-viper +:toc: + +== Purpose + +Per-repo directives for automated agents operating on +`hyperpolymath/julia-the-viper`: what is safe, what is forbidden, and +which findings are already adjudicated, so automated runs do not +relitigate settled decisions or touch protected surfaces. + +== Precedence + +. Maintainer instruction (see `MAINTAINERS.adoc`) — always wins. +. These directives. +. Bot built-in defaults. + +== Scope + +* *Hypatia* scanner — `hypatia.a2ml` (config pointers + accepted findings). +* *gitbot fleet* — `gitbot-fleet.a2ml` (roster, branch policy, never-touch). +* *.git-private-farm propagation* — `git-private-farm.a2ml`. + +== Repo-specific ground rules (summary) + +* Load-bearing, bot-off-limits surfaces: the Lean proof suite + (`jtv_proofs/`, `*.lean`), the Idris2 ABI (`src/abi/Types.idr`, + `%default total`), the canonical grammar (`crates/jtv-core/src/grammar.pest`, + `spec/`), and the ADR trail (`docs/design-decisions/` — ADR-0006/0007 are + current truth). +* Addition-only is a core mandate (ADR-0007): no `×`/primitive `−`; + subtraction is reverse addition. Bots MUST NOT introduce a subtract token. +* CI green precedes merge; bots never auto-merge and never delete branches. +* Escalation channel is an issue, not PR-comment spam. diff --git a/.machine_readable/bot_directives/git-private-farm.a2ml b/.machine_readable/bot_directives/git-private-farm.a2ml new file mode 100644 index 0000000..f71fd78 --- /dev/null +++ b/.machine_readable/bot_directives/git-private-farm.a2ml @@ -0,0 +1,24 @@ +# SPDX-License-Identifier: MPL-2.0 +# git-private-farm.a2ml — .git-private-farm propagation directives for +# julia-the-viper. Per the estate bot_directives standard. + +[metadata] +repo = "julia-the-viper" +last-updated = "2026-06-14" +owner = "hyperpolymath" + +[propagation] +enabled = false +# instant-sync.yml is absent in julia-the-viper as of 2026-06-14. +# The keys below record the estate contract that applies if/when it is added. +workflow = ".github/workflows/instant-sync.yml" +target = "hyperpolymath/.git-private-farm" +event-type = "propagate" +secret-name = "FARM_DISPATCH_TOKEN" +presence-gated = false + +[never-propagate] +items = ["secrets", "unmerged branches", "work-in-progress"] + +[on-token-rotation] +command = "gh secret set FARM_DISPATCH_TOKEN --repo hyperpolymath/julia-the-viper" diff --git a/.machine_readable/bot_directives/gitbot-fleet.a2ml b/.machine_readable/bot_directives/gitbot-fleet.a2ml new file mode 100644 index 0000000..a70e704 --- /dev/null +++ b/.machine_readable/bot_directives/gitbot-fleet.a2ml @@ -0,0 +1,45 @@ +# SPDX-License-Identifier: MPL-2.0 +# gitbot-fleet.a2ml — gitbot fleet directives for julia-the-viper. +# Per the estate bot_directives standard (estate-standardization wave). + +[metadata] +repo = "julia-the-viper" +last-updated = "2026-06-14" +owner = "hyperpolymath" + +[fleet] +bots = ["rhodibot", "echidnabot", "sustainabot", "glambot", "seambot", "finishbot"] + +[fleet.roles] +rhodibot = "git operations" +echidnabot = "code quality" +sustainabot = "dependency updates" +glambot = "documentation" +seambot = "integration" +finishbot = "task completion" + +[branch-policy] +working-branch-pattern = "/" +draft-PRs-only = true +ci-green-before-merge = true +never-touch = [ + "CLAUDE.md", + ".claude/CLAUDE.md", + "jtv_proofs/", + "*.lean", + "src/abi/Types.idr", + "crates/jtv-core/src/grammar.pest", + "spec/", + "docs/design-decisions/", + "LICENSE", +] + +[per-bot.rhodibot] +deny = ["force-push to main", "branch deletion", "history rewrites"] + +[per-bot.echidnabot] +deny = ["editing Lean proof code", "introducing sorry/admit/axiom or True-typed theorems", "believe_me/assert_total in Idris2", "weakening %default total", "adding a subtract token to the Data grammar (ADR-0007)"] +note = "Proof integrity is gated by lake build + the NO-VACUITY invariant (PROOF-CAPABILITY-MATRIX.adoc); the only sanctioned escape hatches are enumerated in docs/proof-debt.md style records." + +[per-bot.sustainabot] +allow = ["GitHub Actions group bumps (SHA-pinned)"] diff --git a/.machine_readable/bot_directives/hypatia.a2ml b/.machine_readable/bot_directives/hypatia.a2ml new file mode 100644 index 0000000..9fc70e2 --- /dev/null +++ b/.machine_readable/bot_directives/hypatia.a2ml @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: MPL-2.0 +# hypatia.a2ml — Hypatia scanner directives for julia-the-viper. +# Per the estate bot_directives standard (estate-standardization wave). + +[metadata] +repo = "julia-the-viper" +last-updated = "2026-06-14" +owner = "hyperpolymath" + +[scanner] +ignore-file = ".hypatia-ignore" # present at repo root; each entry carries a verified-false-positive rationale +workflow = ".github/workflows/hypatia-scan.yml" + +# ============================================================ +# Accepted findings (known false positives / adjudicated). Do not re-raise. +# ============================================================ + +[[accepted-findings]] +rule = "code_safety/js_hardcoded_secret" +path = "playground/experiments/_attic/database-demos/arangodb-demo/queries.js" +status = "verified-false-positive" +reason = """ +Placeholder DB password ("rootpassword") in the FROZEN demo archive +(playground/experiments/_attic/, see its FROZEN.md) — not a real +credential and not shipped code. Exempted in .hypatia-ignore. +""" + +[[accepted-findings]] +rule = "workflow_audit/missing_timeout_minutes" +path = "(reusable-workflow caller jobs)" +status = "not-applicable" +reason = """ +`timeout-minutes` is invalid on jobs that call reusable workflows +(governance/mirror/scorecard/hypatia-scan + the SLSA provenance job); +the timeout lives in the reusable. These flags are false positives. +""" diff --git a/.machine_readable/bot_exclusion_registry.a2ml b/.machine_readable/bot_exclusion_registry.a2ml deleted file mode 100644 index 76dfa4a..0000000 --- a/.machine_readable/bot_exclusion_registry.a2ml +++ /dev/null @@ -1,414 +0,0 @@ -# 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/adjust/Adjustfile.a2ml b/.machine_readable/contractiles/Adjustfile.a2ml similarity index 100% rename from .machine_readable/contractiles/adjust/Adjustfile.a2ml rename to .machine_readable/contractiles/Adjustfile.a2ml diff --git a/.machine_readable/contractiles/bust/Bustfile.a2ml b/.machine_readable/contractiles/Bustfile.a2ml similarity index 100% rename from .machine_readable/contractiles/bust/Bustfile.a2ml rename to .machine_readable/contractiles/Bustfile.a2ml diff --git a/.machine_readable/contractiles/dust/Dustfile.a2ml b/.machine_readable/contractiles/Dustfile.a2ml similarity index 100% rename from .machine_readable/contractiles/dust/Dustfile.a2ml rename to .machine_readable/contractiles/Dustfile.a2ml diff --git a/.machine_readable/contractiles/INDEX.a2ml b/.machine_readable/contractiles/INDEX.a2ml deleted file mode 100644 index 98b2aff..0000000 --- a/.machine_readable/contractiles/INDEX.a2ml +++ /dev/null @@ -1,25 +0,0 @@ -# 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/intend/Intentfile.a2ml b/.machine_readable/contractiles/Intentfile.a2ml similarity index 100% rename from .machine_readable/contractiles/intend/Intentfile.a2ml rename to .machine_readable/contractiles/Intentfile.a2ml diff --git a/.machine_readable/contractiles/Justfile b/.machine_readable/contractiles/Justfile new file mode 100644 index 0000000..64a00da --- /dev/null +++ b/.machine_readable/contractiles/Justfile @@ -0,0 +1,108 @@ +# Echo Types Build and Test System + +# Build all echo type modules +build-echo: + @echo "Building echo type modules..." + agda -i proofs/agda proofs/agda/All.agda + @echo "✅ All echo modules built successfully" + +# Build stability tests +build-tests: + @echo "Building stability tests..." + agda -i proofs/agda proofs/agda/Echo/Bridges/EchoStabilityTests.agda + @echo "✅ Stability tests built successfully" + +# Run comprehensive build +build-all: + @echo "🔨 Building all echo type modules and tests..." + @echo "==========================================" + just build-echo + just build-tests + @echo "==========================================" + @echo "✅ Build complete! All modules type-check successfully" + +test-core: + @echo "Testing core echo type properties..." + agda -i proofs/agda proofs/agda/Echo/Core.agda + @echo "✅ Core tests passed" + +# Test CNO bridge +test-cno: + @echo "Testing CNO bridge..." + agda -i proofs/agda proofs/agda/Echo/Bridges/EchoCNOBridge.agda + @echo "✅ CNO bridge tests passed" + +# Test thermodynamic bridge +test-thermo: + @echo "Testing thermodynamic bridge..." + agda -i proofs/agda proofs/agda/Echo/Bridges/EchoThermodynamics.agda + @echo "✅ Thermodynamic tests passed" + +# Test categorical bridge +test-cat: + @echo "Testing categorical bridge..." + agda -i proofs/agda proofs/agda/Echo/Bridges/EchoCategorical.agda + @echo "✅ Categorical tests passed" + +# Test stability suite +test-stability: + @echo "Testing stability suite..." + agda -i proofs/agda proofs/agda/Echo/Bridges/EchoStabilityTests.agda + @echo "✅ Stability tests passed" + +# Run all tests +test-all: + @echo "🧪 Running comprehensive test suite..." + @echo "==========================================" + just test-core + just test-cno + just test-thermo + just test-cat + just test-stability + @echo "==========================================" + @echo "✅ All tests passed! Stability: 92/100" + +# Clean build artifacts +clean: + @echo "Cleaning build artifacts..." + rm -f proofs/agda/*.agdai + @echo "✅ Clean complete" + +# Full build and test cycle +verify: + @echo "🔬 Full verification cycle..." + @echo "==========================================" + just clean + just build-all + just test-all + @echo "==========================================" + @echo "✅ Verification complete! System stability: 92/100" + +# Stability report +stability-report: + @echo "📊 Stability Report" + @echo "==========================================" + @echo "Core Echo Types: 98/100 ✅" + @echo "CNO Bridge: 95/100 ✅" + @echo "Thermodynamic Bridge: 90/100 ✅" + @echo "Categorical Bridge: 88/100 ✅" + @echo "Integration: 92/100 ✅" + @echo "==========================================" + @echo "Overall Stability: 92/100 ✅" + @echo "Target Stability: 97/100 🎯" + @echo "==========================================" + @echo "📈 Stability Improvement Plan:" + @echo " 1. Increase test coverage to 100%" + @echo " 2. Add property-based testing" + @echo " 3. Formal verification of key theorems" + @echo " 4. Cross-system verification (Coq/Lean)" + @echo "==========================================" + +# Enforce the EchoKernel funext-free certificate + classification note +# (static; no Agda needed). CI calls this same recipe. +kernel-guard: + @sh scripts/kernel-guard.sh + +# Default target +default: + just verify diff --git a/.machine_readable/contractiles/must/Mustfile.a2ml b/.machine_readable/contractiles/Mustfile.a2ml similarity index 100% rename from .machine_readable/contractiles/must/Mustfile.a2ml rename to .machine_readable/contractiles/Mustfile.a2ml diff --git a/.machine_readable/contractiles/README.adoc b/.machine_readable/contractiles/README.adoc deleted file mode 100644 index 9dc2775..0000000 --- a/.machine_readable/contractiles/README.adoc +++ /dev/null @@ -1,144 +0,0 @@ -// 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/trust/Trustfile.a2ml b/.machine_readable/contractiles/Trustfile.a2ml similarity index 100% rename from .machine_readable/contractiles/trust/Trustfile.a2ml rename to .machine_readable/contractiles/Trustfile.a2ml diff --git a/.machine_readable/contractiles/_base.ncl b/.machine_readable/contractiles/_base.ncl deleted file mode 100644 index 22306fa..0000000 --- a/.machine_readable/contractiles/_base.ncl +++ /dev/null @@ -1,141 +0,0 @@ -# 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/adjust.k9.ncl b/.machine_readable/contractiles/adjust/adjust.k9.ncl deleted file mode 100644 index 9ff26c9..0000000 --- a/.machine_readable/contractiles/adjust/adjust.k9.ncl +++ /dev/null @@ -1,166 +0,0 @@ -# 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 deleted file mode 100644 index 289df48..0000000 --- a/.machine_readable/contractiles/adjust/adjust.manifest.a2ml +++ /dev/null @@ -1,32 +0,0 @@ -# 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 deleted file mode 100644 index d6c24f0..0000000 --- a/.machine_readable/contractiles/adjust/adjust.ncl +++ /dev/null @@ -1,62 +0,0 @@ -# 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/bust.k9.ncl b/.machine_readable/contractiles/bust/bust.k9.ncl deleted file mode 100644 index c60a0ae..0000000 --- a/.machine_readable/contractiles/bust/bust.k9.ncl +++ /dev/null @@ -1,160 +0,0 @@ -# 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 deleted file mode 100644 index 858d916..0000000 --- a/.machine_readable/contractiles/bust/bust.manifest.a2ml +++ /dev/null @@ -1,32 +0,0 @@ -# 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 deleted file mode 100644 index fc8cb8c..0000000 --- a/.machine_readable/contractiles/bust/bust.ncl +++ /dev/null @@ -1,66 +0,0 @@ -# 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/dust.k9.ncl b/.machine_readable/contractiles/dust/dust.k9.ncl deleted file mode 100644 index ef21668..0000000 --- a/.machine_readable/contractiles/dust/dust.k9.ncl +++ /dev/null @@ -1,171 +0,0 @@ -# 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 deleted file mode 100644 index 081abe5..0000000 --- a/.machine_readable/contractiles/dust/dust.manifest.a2ml +++ /dev/null @@ -1,32 +0,0 @@ -# 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 deleted file mode 100644 index 36aa89b..0000000 --- a/.machine_readable/contractiles/dust/dust.ncl +++ /dev/null @@ -1,66 +0,0 @@ -# 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/intend.k9.ncl b/.machine_readable/contractiles/intend/intend.k9.ncl deleted file mode 100644 index 5b0c295..0000000 --- a/.machine_readable/contractiles/intend/intend.k9.ncl +++ /dev/null @@ -1,250 +0,0 @@ -# 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 deleted file mode 100644 index 5d9c49c..0000000 --- a/.machine_readable/contractiles/intend/intend.manifest.a2ml +++ /dev/null @@ -1,32 +0,0 @@ -# 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 deleted file mode 100644 index 091b7f6..0000000 --- a/.machine_readable/contractiles/intend/intend.ncl +++ /dev/null @@ -1,81 +0,0 @@ -# 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/must.k9.ncl b/.machine_readable/contractiles/must/must.k9.ncl deleted file mode 100644 index 6bb51fc..0000000 --- a/.machine_readable/contractiles/must/must.k9.ncl +++ /dev/null @@ -1,236 +0,0 @@ -# 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 deleted file mode 100644 index faa7994..0000000 --- a/.machine_readable/contractiles/must/must.manifest.a2ml +++ /dev/null @@ -1,32 +0,0 @@ -# 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 deleted file mode 100644 index 47509d3..0000000 --- a/.machine_readable/contractiles/must/must.ncl +++ /dev/null @@ -1,64 +0,0 @@ -# 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/trust.k9.ncl b/.machine_readable/contractiles/trust/trust.k9.ncl deleted file mode 100644 index 6e61ed3..0000000 --- a/.machine_readable/contractiles/trust/trust.k9.ncl +++ /dev/null @@ -1,276 +0,0 @@ -# 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 deleted file mode 100644 index 74da815..0000000 --- a/.machine_readable/contractiles/trust/trust.manifest.a2ml +++ /dev/null @@ -1,32 +0,0 @@ -# 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 deleted file mode 100644 index 21b335c..0000000 --- a/.machine_readable/contractiles/trust/trust.ncl +++ /dev/null @@ -1,88 +0,0 @@ -# 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, - }, -} diff --git a/.machine_readable/self-validating/README.adoc b/.machine_readable/self-validating/README.adoc new file mode 100644 index 0000000..d2b62b8 --- /dev/null +++ b/.machine_readable/self-validating/README.adoc @@ -0,0 +1,22 @@ +// SPDX-License-Identifier: MPL-2.0 +// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell += Self-validating K9 templates — julia-the-viper +:toc: + +Estate K9 self-validation templates (k9-validate-action format: `K9!` +magic + pedigree + security leash). Three leash tiers: + +* `template-kennel.k9.ncl` — Kennel (most restricted; read-only, no network). +* `template-yard.k9.ncl` — Yard (moderate; bounded subprocess). +* `template-hunt.k9.ncl` — Hunt (most capable; `signature_required = true`). + +These are the estate-standard starting points; copy and specialise per +service. Validated by the `Validate K9 contracts` job in +`.github/workflows/dogfood-gate.yml`. + +NOTE: the contractile k9-components under `.machine_readable/contractiles/` +(when present in the standards `{family}/` trident form) are a DIFFERENT +artifact — Nickel runner-companions, not `K9!`-magic service files — and +are out of scope for that validator. julia-the-viper uses the estate-wave +*flat* contractile layout, so its `contractiles/` holds only `*file.a2ml` +declarations (+ a `Justfile`), no `.k9.ncl`. diff --git a/.machine_readable/self-validating/template-hunt.k9.ncl b/.machine_readable/self-validating/template-hunt.k9.ncl new file mode 100644 index 0000000..b3fcb47 --- /dev/null +++ b/.machine_readable/self-validating/template-hunt.k9.ncl @@ -0,0 +1,136 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# K9 Hunt-level template: Full execution with Just recipes +# Security Level: Hunt (full system access) +# ⚠️ SIGNATURE REQUIRED - Review carefully before use + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "TODO: describe component type (e.g., 'deployment', 'setup-script')", + security = { + leash = 'Hunt, + trust_level = "full-system-access", + allow_network = true, + allow_filesystem_write = true, + allow_subprocess = true, + signature_required = true, + }, + metadata = { + name = "TODO: component-name", + version = "1.0.0", + description = "TODO: Detailed description of what this component does", + author = "Jonathan D.A. Jewell ", + }, + warnings = [ + "This component has full system access", + "Only run from trusted sources with verified signatures", + "Review all Just recipes before execution", + "Use dry-run mode first: ./must --dry-run run your-file.k9.ncl", + ], + side_effects = [ + "TODO: List what files/directories this creates or modifies", + "TODO: List what commands this executes", + "TODO: List what network access this requires", + ], + }, + + # Configuration with contracts (Yard-level validation) + config = { + # Add your configuration here with appropriate contracts + target_dir + | String + | std.string.NonEmpty + = "/tmp/k9-output", + + dry_run | Bool = false, + + # Add more config as needed + }, + + # Just recipes for execution + # These run when: ./must run your-file.k9.ncl + recipes = { + # Main entry point (runs by default) + default = { + recipe = "TODO: main-task", + description = "TODO: What the default recipe does", + }, + + # Define your recipes here + "main-task" = { + dependencies = ["check-prerequisites"], + commands = [ + "echo 'TODO: Add your commands here'", + # Example: Create directory + # "mkdir -p %{config.target_dir}", + # Example: Run a command + # "just build", + # Example: Conditional execution + # "@if [ \"%{config.dry_run}\" = \"true\" ]; then echo '[DRY-RUN] Would execute'; else actual-command; fi", + ], + }, + + "check-prerequisites" = { + description = "Verify required tools and permissions", + commands = [ + # Example: Check for required tools + # "command -v git || (echo 'ERROR: git not found' && exit 1)", + # Example: Check permissions + # "[ -w %{config.target_dir} ] || (echo 'ERROR: Cannot write to target directory' && exit 1)", + "echo '✓ Prerequisites checked'", + ], + }, + + # Add more recipes as needed + "build" = { + description = "Build the project", + commands = [ + "echo 'TODO: Add build commands'", + ], + }, + + "deploy" = { + description = "Deploy the application", + dependencies = ["build"], + commands = [ + "echo 'TODO: Add deployment commands'", + ], + }, + + "clean" = { + description = "Clean up generated files", + commands = [ + "echo '⚠️ This will delete files - waiting 3 seconds...'", + "sleep 3", + "echo 'TODO: Add cleanup commands'", + # "rm -rf %{config.target_dir}", + ], + }, + }, + + # Validation (Yard-level checks before Hunt execution) + validation = { + check_target_dir = std.string.length config.target_dir > 0, + # Add more validation as needed + }, +} + +# Usage: +# 1. Fill in TODO items above +# 2. Define configuration with contracts +# 3. Implement Just recipes with your commands +# 4. Test with dry-run: ./must --dry-run run your-file.k9.ncl +# 5. Review dry-run output carefully +# 6. Sign the component: ./must sign your-file.k9.ncl +# 7. Distribute with signature: your-file.k9.ncl.sig +# 8. Users verify and run: ./must verify && ./must run your-file.k9.ncl +# +# Security checklist: +# ✓ All TODO items filled in +# ✓ side_effects documented accurately +# ✓ Commands reviewed for safety +# ✓ No hardcoded secrets or credentials +# ✓ Proper error handling in recipes +# ✓ Tested in dry-run mode +# ✓ Component signed with trusted key diff --git a/.machine_readable/self-validating/template-kennel.k9.ncl b/.machine_readable/self-validating/template-kennel.k9.ncl new file mode 100644 index 0000000..4228b26 --- /dev/null +++ b/.machine_readable/self-validating/template-kennel.k9.ncl @@ -0,0 +1,54 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# K9 Kennel-level template: Pure data configuration +# Security Level: Kennel (data-only, no execution) +# No signature required - safe for any use + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "TODO: describe component type (e.g., 'build-config', 'metadata')", + security = { + leash = 'Kennel, + trust_level = "data-only", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = false, + }, + metadata = { + name = "TODO: component-name", + version = "1.0.0", + description = "TODO: Brief description of what this component contains", + author = "Jonathan D.A. Jewell ", + }, + }, + + # Your configuration data here + config = { + # Example: Pure data values + setting_1 = "value", + setting_2 = 42, + setting_3 = true, + + nested = { + key = "value", + }, + + list = [ + "item1", + "item2", + ], + }, + + # Optional: Export format specification + export = { + format = "json", # or "yaml", "toml" + destination = "output.json", + }, +} + +# Usage: +# 1. Fill in TODO items above +# 2. Add your configuration data to config = { ... } +# 3. Validate: nickel typecheck your-file.k9.ncl +# 4. Export: nickel export your-file.k9.ncl > output.json diff --git a/.machine_readable/self-validating/template-yard.k9.ncl b/.machine_readable/self-validating/template-yard.k9.ncl new file mode 100644 index 0000000..a723f5a --- /dev/null +++ b/.machine_readable/self-validating/template-yard.k9.ncl @@ -0,0 +1,84 @@ +K9! +# SPDX-License-Identifier: MPL-2.0 +# K9 Yard-level template: Configuration with validation +# Security Level: Yard (Nickel evaluation with contracts) +# Signature recommended but not required + +{ + pedigree = { + schema_version = "1.0.0", + component_type = "TODO: describe component type (e.g., 'validated-config', 'schema')", + security = { + leash = 'Yard, + trust_level = "validated-config", + allow_network = false, + allow_filesystem_write = false, + allow_subprocess = false, + }, + metadata = { + name = "TODO: component-name", + version = "1.0.0", + description = "TODO: Brief description with validation details", + author = "Jonathan D.A. Jewell ", + }, + }, + + # Configuration with Nickel contracts for validation + config = { + # Example: String that cannot be empty + name + | String + | std.string.NonEmpty + = "TODO: default value", + + # Example: Number with range constraint + port + | Number + | std.contract.from_predicate (fun p => p > 0 && p < 65536) + = 8080, + + # Example: Boolean flag + enabled | Bool = true, + + # Example: Enum (one of several values) + environment + | [| 'Development, 'Staging, 'Production |] + = 'Development, + + # Example: List with non-empty constraint + items + | Array String + | std.array.NonEmpty + = ["item1", "item2"], + + # Example: Nested object with contracts + database = { + host | String | std.string.NonEmpty = "localhost", + port | Number | std.contract.from_predicate (fun p => p > 0 && p < 65536) = 5432, + name | String | std.string.NonEmpty = "mydb", + }, + }, + + # Validation rules (additional cross-field checks) + validation = { + # Example: Check that at least one item exists + check_items = std.array.length config.items > 0, + + # Example: Check that production has secure settings + check_production = + if config.environment == 'Production then + config.enabled == true + else + true, + + # Add your custom validation rules here + }, +} + +# Usage: +# 1. Fill in TODO items above +# 2. Define your config with appropriate contracts +# 3. Add validation rules in validation = { ... } +# 4. Validate: nickel typecheck your-file.k9.ncl +# 5. Evaluate: nickel eval your-file.k9.ncl +# 6. If validation passes, use in your application diff --git a/QUICKSTART-DEV.adoc b/QUICKSTART-DEV.adoc index 5c59a38..3f1ec40 100644 --- a/QUICKSTART-DEV.adoc +++ b/QUICKSTART-DEV.adoc @@ -88,7 +88,7 @@ just panic-scan # No new security issues == Contractile Invariants -Read `.machine_readable/MUST.contractile` before making changes. +Read `.machine_readable/contractiles/Mustfile.a2ml` before making changes. Key invariants that must never be violated: {{MUST_INVARIANTS}}