recon-silly-ation

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.

Table of Contents

• What this is
• ForthWall
• Proof and delivery status
• Quick start
• What you get
• Repository map
• Where to go next
• Licence

What this is

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 TEST-NEEDS and 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 AI-agent gatekeeper protocol, a formally-typed ABI/FFI seam (Idris2 + Zig), container and reproducible-build scaffolding, and governance infrastructure.

Quick start

git clone https://github.com/hyperpolymath/recon-silly-ation.git
cd recon-silly-ation

# See the available tasks:
just                     # lists all phases (build, test, validate, audit, ...)

# Build the Zig FFI bridge:
just build

# Check the repo still satisfies the RSR shape:
just validate            # structure + metadata checks

What you get

• Machine-readable metadata (.machine_readable/6a2/) — STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC, NEUROSYM, CLADE, and anchors/ANCHOR, in a2ml, so tools and agents can read the project’s state and boundaries.

• AI gatekeeper protocol — 0-AI-MANIFEST.a2ml is the universal entry point that tells an AI agent how to work in this repo before it touches anything.

• Typed ABI/FFI seam — src/interface/Abi/ (Idris2 type + layout proofs) over src/interface/ffi/ (Zig implementation), with generated C headers.

• CI/CD — GitHub Actions for quality, security (CodeQL, Scorecard, secret scanning), multi-forge mirroring, and RSR anti-pattern enforcement.

• Supply-chain & reproducibility — container layering (stapeln), Nix/Guix shells, SBOM, and signing hooks.

• Governance — GOVERNANCE.adoc, MAINTAINERS.adoc, .github/ community health files, and a release AUDIT.adoc gate.

Repository map

Path	What lives there
0-AI-MANIFEST.a2ml	Universal entry point for AI agents (read first).
.machine_readable/	Project metadata, policies, contractiles, AI configs.
src/interface/	Typed ABI (Idris2) + FFI (Zig) + generated headers.
docs/	Onboarding, status, governance, practice, decisions.
build/, Justfile	Task orchestration (just phases delegate to build/just/*.just).
.github/	Workflows + community health files.
tests/, benches/	Test suites and benchmarks.

Where to go next

• EXPLAINME.adoc — the engineering deep-dive: how the pieces actually work.

• AFFIRMATION.adoc — the dated, signed honesty snapshot of the repo’s true state.

• AUDIT.adoc — the release audit gate.

• .machine_readable/ai/PLACEHOLDERS.adoc — the full placeholder reference.

Licence

Released under the Mozilla Public License 2.0 unless a per-file SPDX-License-Identifier says otherwise.