diff --git a/.machine_readable/6a2/STATE.a2ml b/.machine_readable/6a2/STATE.a2ml index a37a36d..8d5c0ca 100644 --- a/.machine_readable/6a2/STATE.a2ml +++ b/.machine_readable/6a2/STATE.a2ml @@ -6,12 +6,12 @@ [metadata] project = "recon-silly-ation" version = "0.1.0" -last-updated = "2026-07-27" +last-updated = "2026-08-28" status = "active" # active | paused | archived [project-context] name = "recon-silly-ation" -purpose = "WASM document reconciliation, built around the ReconForth VM. Registered in the reposystem tool ecosystem as an `interop`-role, `extracted` (gitlink submodule) tool with a single declared action: `reconcile`. Scaffolded from rsr-template-repo, so it ships with CI/CD, AI manifests, ABI/FFI standards, container ecosystem, and governance infrastructure inherited from there." +purpose = "Experimental cross-document consistency reconciliation for repository documentation, history, metadata, terminology, language policy, and attribution. ForthWall is a proposed bounded Forth rule engine beneath the reconciler, not the product identity and not an implemented capability. Registered in reposystem as an `interop`-role, `extracted` tool with a planned `reconcile` action." completion-percentage = 20 [position] @@ -22,19 +22,20 @@ maturity = "experimental" # experimental | alpha | beta | production | lts milestones = [ { name = "RSR scaffolding instantiated (CI/CD, AI manifests, governance, container packaging)", completion = 100 }, { name = "Typed ABI/FFI seam (Idris2 Abi/{Types,Layout,Foreign}.idr + Zig src/interface/ffi)", completion = 100 }, - { name = "ReconForth VM compiled to WebAssembly", completion = 0 }, + { name = "Bounded ForthWall VM compiled to WebAssembly", completion = 0 }, { name = "Document reconciliation logic (the actual `reconcile` action)", completion = 0 }, ] [blockers-and-issues] # No active blockers. The gap is scope, not obstruction: the RSR scaffolding -# and ABI/FFI seam are in place, but the ReconForth VM / WASM reconciliation +# and ABI/FFI seam are in place, but the ForthWall VM / WASM reconciliation # logic itself has not been implemented yet. [critical-next-actions] actions = [ - "Implement the ReconForth VM and compile it to WebAssembly.", + "Specify, implement, and prove the bounded ForthWall VM, then compile it to WebAssembly.", "Implement the `reconcile` action behind the ABI/FFI seam.", + "Gate every capability claim on planted positive/negative, confinement, idempotence, non-interference, attribution-scope, adversarial, and independently verified end-to-end tests.", "Populate src/core, src/definitions, src/aspects, src/errors, src/bridges beyond their current scaffolding.", ] diff --git a/.machine_readable/6a2/anchors/ANCHOR.a2ml b/.machine_readable/6a2/anchors/ANCHOR.a2ml index b74359c..9858628 100644 --- a/.machine_readable/6a2/anchors/ANCHOR.a2ml +++ b/.machine_readable/6a2/anchors/ANCHOR.a2ml @@ -5,7 +5,7 @@ [metadata] version = "1.0.0" -last-updated = "2026-07-27" +last-updated = "2026-08-28" [anchor] schema = "hyperpolymath.anchor/1" @@ -21,7 +21,7 @@ purpose = [ [identity] project = "recon-silly-ation" kind = "tool" # language | library | service | tool -one-sentence = "Reconciles documents via a WASM-hosted ReconForth virtual machine, as an interop component of the reposystem tool ecosystem." +one-sentence = "Finds and safely reconciles cross-document and repository inconsistencies; its proposed bounded ForthWall execution layer is not yet implemented or proved." domain = "document reconciliation" [semantic-authority] diff --git a/.machine_readable/bot_directives/methodology.a2ml b/.machine_readable/bot_directives/methodology.a2ml index 2aa1db7..92f1662 100644 --- a/.machine_readable/bot_directives/methodology.a2ml +++ b/.machine_readable/bot_directives/methodology.a2ml @@ -9,7 +9,7 @@ [metadata] version = "1.0.0" -last-updated = "2026-07-27" +last-updated = "2026-08-28" spec = "https://github.com/hyperpolymath/standards/blob/main/agentic-a2ml/docs/ADR-002-methodology-layer.adoc" # ============================================================================ @@ -55,7 +55,7 @@ perfective = 10 # % for SPDX headers, doc updates, formatting, style # Customise this per project — the template default is generic. [methodology.unique-strength] -description = "Runs the ReconForth VM compiled to WebAssembly for portable, sandboxed document reconciliation." +description = "Reconciles evidenced cross-document inconsistencies; a bounded, capability-restricted ForthWall VM is proposed as an optional execution layer and is not yet implemented or proved." deepen-not-broaden = true # ============================================================================ diff --git a/.machine_readable/contractiles/Intentfile.a2ml b/.machine_readable/contractiles/Intentfile.a2ml index 945dc1d..e657da7 100644 --- a/.machine_readable/contractiles/Intentfile.a2ml +++ b/.machine_readable/contractiles/Intentfile.a2ml @@ -20,17 +20,18 @@ # contractile for hard gates. @abstract: -North-star contractile for recon-silly-ation, an RSR-compliant repository -instantiated from rsr-template-repo. It reconciles documents via a -WASM-hosted ReconForth VM, as an interop component of the reposystem tool -ecosystem. +North-star contractile for recon-silly-ation, an experimental cross-document +consistency reconciler. ForthWall is its proposed bounded Forth rule layer, not +its product identity and not yet an implemented or proved capability. @end ## Purpose -recon-silly-ation reconciles documents by running the ReconForth virtual -machine compiled to WebAssembly, registered in `reposystem` as an -`interop`-role tool exposing a `reconcile` action. +recon-silly-ation performs reconnaissance for small inconsistencies and +reconciles documentation, history, metadata, terminology, language policy, and +attribution without allowing a local correction to silently redefine unrelated +surfaces. It is registered in `reposystem` as an `interop`-role tool exposing a +planned `reconcile` action. ## Anti-Purpose @@ -38,6 +39,8 @@ This repository is NOT: - The RSR template itself (that is rsr-template-repo, upstream) - A general-purpose project scaffold (it is an instantiated consumer) - A runtime library that other repos should copy wholesale +- A licence to normalise ambiguous text or rewrite beyond evidenced scope +- An operational ForthWall VM until its implementation and proofs are present ## If In Doubt @@ -65,13 +68,13 @@ If you are unsure whether a change is in scope, ask. Sensitive areas: ### Near Horizon #### e2e-reconcile-roundtrip -- description: tests/e2e.sh exercises a real ReconForth reconcile round-trip via the WASM build +- description: tests/e2e.sh exercises a real ForthWall reconcile round-trip via the WASM build, including evidence preservation and independent verification - horizon: near - status: declared ### Mid Horizon #### formal-verification -- description: Idris2 proofs for all critical contractile invariants +- description: Idris2 proofs cover VM semantics, capability confinement, scope preservation, idempotence, non-interference, stale-input refusal, and attribution locality - horizon: mid - status: declared diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index b048d1c..4f921fa 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -26,11 +26,13 @@ repos: name: Validate A2ML manifests # --- K9 contract validation --- - - repo: https://github.com/hyperpolymath/k9-pre-commit - rev: main + - repo: local hooks: - id: validate-k9 name: Validate K9 contracts + entry: .githooks/validate-k9.sh + language: system + pass_filenames: false # --- Shell linting --- - repo: https://github.com/shellcheck-py/shellcheck-py diff --git a/0-AI-MANIFEST.a2ml b/0-AI-MANIFEST.a2ml index 8b1848c..c0bb118 100644 --- a/0-AI-MANIFEST.a2ml +++ b/0-AI-MANIFEST.a2ml @@ -5,11 +5,11 @@ # [metadata] version = "0.1.0" -last-updated = "2026-07-27" +last-updated = "2026-08-28" [project] name = "recon-silly-ation" -purpose = "WASM document reconciliation (ReconForth VM); interop component of the reposystem tool ecosystem." +purpose = "Experimental cross-document consistency reconciliation for names, links, claims, attribution, terminology, language style, and repository metadata; the proposed bounded ForthWall engine is not yet implemented or proved." [ai-allocation] agents = [ diff --git a/README.adoc b/README.adoc index ae193b2..d238b21 100644 --- a/README.adoc +++ b/README.adoc @@ -9,16 +9,75 @@ image:https://img.shields.io/badge/OpenSSF-Best_Practices-green?logo=opensources image:https://img.shields.io/badge/License-MPL_2.0-blue.svg[License: MPL-2.0,link="https://opensource.org/licenses/MPL-2.0"] image:https://api.thegreenwebfoundation.org/greencheckimage/github.com[Green Web,link="https://www.thegreenwebfoundation.org/green-web-check/?url=github.com"] -WASM document reconciliation, built around the ReconForth VM. It is an -`interop` component of the `reposystem` tool ecosystem (see -`reposystem/config/tools.ncl`), exposing a `reconcile` action. +An experimental cross-document consistency reconciler. It finds small-looking +contradictions that make a repository's documentation, history, metadata, and +attribution disagree. It is registered as an `interop` component of the +`reposystem` tool ecosystem, exposing a planned `reconcile` action. == What this is -recon-silly-ation reconciles documents by running the ReconForth virtual -machine compiled to WebAssembly. It is registered in `reposystem` as an -`interop`-role tool with `status = 'extracted` (a gitlink submodule of -`reposystem`), whose sole declared action is `reconcile`. +The name combines *reconnaissance for silly inconsistencies* with +*reconciliation*: inspect every relevant surface, retain evidence for each +disagreement, and propose the smallest coherent resolution. + +The intended scope includes: + +* project or file renames that were not propagated through READMEs, wikis, + examples, links, repository metadata, and the GitHub description; +* changelog or release claims that do not match the change, omit consequential + side effects, or continue foregrounding obsolete generations; +* contributor credit that is missing where it belongs or incorrectly expands + into repository-wide authorship; +* inconsistent language policy (including UK, US, and Oxford English), + terminology, capitalisation, analogies, and conceptual explanations; +* references to files, faults, features, versions, commands, or names that no + longer exist; and +* explanations that cannot all be true, even when a superficial text + normalisation would make them look alike. + +Ambiguous conflicts are findings for review, not permission to rewrite. Every +finding and proposed edit must retain its sources, evidence spans, and +provenance. + +== ForthWall + +*ForthWall* is the proposed name for an optional bounded Forth rule engine +beneath the reconciler. It is not the meaning of `recon` in the project name, +not the whole product, and not currently an implemented capability. + +The intended wall admits only declared inputs and approved document-level +words. It must not expose raw memory, arbitrary filesystem access, shell +execution, networking, or unrestricted writes. It must refuse automatic repair +when evidence is ambiguous, inputs are stale, parsers disagree, or coordinates +have drifted. + +== Proof and delivery status + +This repository currently contains project scaffolding and an ABI/FFI seam; it +does *not* contain a proven reconciliation engine or an operational ForthWall +VM. The machine-readable state records both the VM and actual `reconcile` +action as 0% complete. Design documents and deterministic execution alone are +not evidence that a proposed edit is semantically correct. + +A capability may be described as delivered only when the repository contains +independently reproducible evidence for it: + +* an executable specification for the VM and every document-level word; +* planted positive and negative fixtures for every inconsistency class; +* exact input hashes, evidence spans, proposed changes, and replayable traces; +* idempotence, non-interference, scope-confinement, and stale-input tests; +* attribution tests proving local credit cannot become global authorship; +* adversarial and cross-format end-to-end fixtures; and +* an independent verifier for every automatically applied edit. + +Until those gates exist and pass, results are proposals requiring review and +automatic mutation must remain disabled. See +link:docs/status/TEST-NEEDS.adoc[`TEST-NEEDS`] and +https://github.com/hyperpolymath/recon-silly-ation/issues/44[issue #44]. + +The repository remains registered in `reposystem` as an `interop`-role tool +with status = `extracted` (a gitlink submodule), whose sole declared action is +`reconcile`. The repository is scaffolded from the *Rhodium Standard Repository (RSR)* template, so it ships with CI/CD, machine-readable project metadata, an diff --git a/build/guix.scm b/build/guix.scm index 3fc6d78..24a4eed 100644 --- a/build/guix.scm +++ b/build/guix.scm @@ -47,10 +47,11 @@ (inputs (list)) (home-page "https://github.com/hyperpolymath/recon-silly-ation") - (synopsis "WASM document reconciliation (ReconForth VM)") - (description "recon-silly-ation reconciles documents by running the -ReconForth virtual machine compiled to WebAssembly. It is an interop -component of the reposystem tool ecosystem, exposing a reconcile action.") + (synopsis "Experimental cross-document consistency reconciler") + (description "recon-silly-ation is intended to find and safely reconcile +contradictions across documentation, history, metadata, terminology, language +policy, and attribution. Its proposed bounded ForthWall execution layer and +reconcile action are not yet implemented or proved.") (license (list ;; MPL-2.0 extends MPL-2.0 mpl2.0))) diff --git a/container/Containerfile b/container/Containerfile index 90ebcc6..2f68ec3 100644 --- a/container/Containerfile +++ b/container/Containerfile @@ -70,7 +70,7 @@ FROM cgr.dev/chainguard/wolfi-base:latest # OCI image labels (compatible with cerro-torre .ctp bundle metadata) LABEL org.opencontainers.image.title="recon-silly-ation" \ - org.opencontainers.image.description="WASM document reconciliation (ReconForth VM)." \ + org.opencontainers.image.description="Experimental cross-document consistency reconciler; proposed bounded, capability-restricted ForthWall engine not yet implemented or proved." \ org.opencontainers.image.url="https://github.com/hyperpolymath/recon-silly-ation" \ org.opencontainers.image.source="https://github.com/hyperpolymath/recon-silly-ation" \ org.opencontainers.image.vendor="hyperpolymath" \ diff --git a/container/manifest.toml b/container/manifest.toml index 6be9af8..90404d5 100644 --- a/container/manifest.toml +++ b/container/manifest.toml @@ -9,7 +9,7 @@ name = "recon-silly-ation" version = "0.1.0" revision = 1 -summary = "WASM document reconciliation (ReconForth VM)." +summary = "Experimental cross-document consistency reconciler; proposed bounded, capability-restricted ForthWall engine not yet implemented or proved." description = """ recon-silly-ation — containerised service packaged as a verified cerro-torre .ctp bundle with Ed25519 signing and full provenance diff --git a/docs/onboarding/QUICKSTART-MAINTAINER.adoc b/docs/onboarding/QUICKSTART-MAINTAINER.adoc index cc808e0..964d80e 100644 --- a/docs/onboarding/QUICKSTART-MAINTAINER.adoc +++ b/docs/onboarding/QUICKSTART-MAINTAINER.adoc @@ -6,9 +6,11 @@ == Overview -This guide covers packaging, deploying, and maintaining recon-silly-ation -(WASM document reconciliation via the ReconForth VM) for distribution on -your platform. +This guide records the intended packaging and maintenance surface for +recon-silly-ation, an experimental cross-document consistency reconciler. The +actual reconciliation engine and its proposed bounded ForthWall VM are not yet +implemented or proved; the commands below exercise scaffolding and must not be +treated as evidence of a distributable reconciliation runtime. == Runtime Dependencies @@ -87,8 +89,9 @@ Fallback: `$HOME/.config/recon_silly_ation/config.toml` == Health Checks -recon-silly-ation is an FFI/WASM library (the ReconForth VM), not a -standalone executable, so there is no `just run`. Use: +recon-silly-ation currently has an FFI/WASM scaffold, not an operational +ForthWall library or standalone reconciliation executable, so there is no +`just run`. The following commands check only the present scaffold: [source,bash] ---- diff --git a/docs/status/TEST-NEEDS.adoc b/docs/status/TEST-NEEDS.adoc index 2151132..c76817e 100644 --- a/docs/status/TEST-NEEDS.adoc +++ b/docs/status/TEST-NEEDS.adoc @@ -2,7 +2,7 @@ // Copyright (c) Jonathan D.A. Jewell = TEST-NEEDS: recon-silly-ation -== Current State (Updated 2026-07-27) +== Current State (Updated 2026-08-28) recon-silly-ation was instantiated from `rsr-template-repo`. This document previously described the *template's own* test suite for validating @@ -20,7 +20,7 @@ machinery has now been removed as no longer applicable: | *Source modules* | 6 | 3 Idris2 ABI (Foreign, Layout, Types), 2 Zig FFI (build, main), 1 Zig integration test | *Unit tests* | 0 | None in main source (inline tests in main.zig, if any) | *Integration tests* | 1 | `src/interface/ffi/test/integration_test.zig` — still template-shaped (see below) -| *E2E tests* | 1 | `tests/e2e.sh` — banner + mostly-commented example matrix, not yet wired to real ReconForth flows +| *E2E tests* | 1 | tests/e2e.sh — banner + mostly-commented example matrix, not yet wired to real reconciliation or ForthWall flows | *Aspect tests* | 1 | `tests/aspect_tests.sh` — cross-cutting invariant checks | *Workflow tests* | 1 | `tests/workflows/validate_workflows_test.sh` — validates GitHub Actions workflow structure |=== @@ -33,9 +33,36 @@ machinery has now been removed as no longer applicable: `recon_silly_ation_*` FFI functions in `src/interface/ffi/src/main.zig`. * [ ] `tests/e2e.sh` has a real banner and structure but its actual assertions are still example/commented-out matrix entries — it does not - yet exercise a real ReconForth reconciliation round-trip. + yet exercise a real reconciliation or ForthWall round-trip. * [ ] No fuzz harness is wired up yet (see `benches/` history above). +== Capability Evidence Required + +The project purpose is broader than its proposed bounded ForthWall VM. Each capability +must have independently reproducible evidence before it may be marked complete +or operational: + +* [ ] planted positive and negative fixtures for project/file renames, stale + links and claims, changelog accuracy, language-style consistency, terminology, + conceptual analogies, and attribution scope; +* [ ] punctuation-sensitive semantic fixtures, including vocative boundaries + and other cases where punctuation changes grammatical roles or meaning; +* [ ] executable specifications for ForthWall's VM and every exposed + document-level word; +* [ ] exact input hashes, source/evidence spans, proposed changes, and + deterministic replay traces; +* [ ] idempotence, non-interference, capability confinement, stale-input + refusal, parser-disagreement refusal, and coordinate-drift refusal; +* [ ] attribution tests proving a local contributor credit cannot become + repository-wide authorship; +* [ ] adversarial, malformed-input, Unicode-confusable, cross-format, and + cross-surface end-to-end fixtures; and +* [ ] an independent verifier for every automatically applied edit. + +A repeatable edit is not necessarily a correct edit. Automatic mutation must +remain disabled until these gates exist and pass; ambiguous findings require +human review. + == CRG Notes * *License*: MPL-2.0 on all new files @@ -44,6 +71,7 @@ machinery has now been removed as no longer applicable: == Next Steps * [ ] Give `integration_test.zig` real test bodies against the FFI surface. -* [ ] Wire `tests/e2e.sh` to a real ReconForth reconcile round-trip via the - WASM build. +* [ ] Wire `tests/e2e.sh` to a real ForthWall reconcile round-trip via the WASM + build, with bounded capabilities and independent verification of every applied + edit and the final document state. * [ ] Integrate `just test` / `just e2e` / `just aspect` into CI.