From 9df4b91a21dbf2619dd6d04789e7243f9159d4a7 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:47:00 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.md => ARCHITECTURE.adoc | 41 ++++----- CHANGELOG.adoc | 32 +++++++ CHANGELOG.md | 31 ------- CONTRIBUTING.adoc | 52 ++++++++++++ CONTRIBUTING.md | 50 ----------- GOVERNANCE.adoc | 44 ++++++++++ GOVERNANCE.md | 49 ----------- README.adoc | 37 +++++++++ README.md | 27 ------ agent-self-review-precommit.adoc | 120 +++++++++++++++++++++++++++ agent-self-review-precommit.md | 114 ------------------------- docs/tech-debt-2026-05-26.adoc | 71 ++++++++++++++++ docs/tech-debt-2026-05-26.md | 57 ------------- 13 files changed, 374 insertions(+), 351 deletions(-) rename ARCHITECTURE.md => ARCHITECTURE.adoc (67%) create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 README.adoc delete mode 100644 README.md create mode 100644 agent-self-review-precommit.adoc delete mode 100644 agent-self-review-precommit.md create mode 100644 docs/tech-debt-2026-05-26.adoc delete mode 100644 docs/tech-debt-2026-05-26.md diff --git a/ARCHITECTURE.md b/ARCHITECTURE.adoc similarity index 67% rename from ARCHITECTURE.md rename to ARCHITECTURE.adoc index b998e55..16d88f6 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.adoc @@ -1,19 +1,14 @@ - +== Architecture -# Architecture - -`technical-notes` is a documentation archive, not a software project: +`+technical-notes+` is a documentation archive, not a software project: it holds short, citable technical notes (Markdown, optionally with a -Typst source and rendered PDF) that are individually deposited on -Zenodo with a DOI. There is no source code, no build system, and no -runtime component. +Typst source and rendered PDF) that are individually deposited on Zenodo +with a DOI. There is no source code, no build system, and no runtime +component. -## Layout +=== Layout -``` +.... . ├── README.md # index of published notes (title, date, DOI) ├── .md # note source (Markdown) @@ -24,18 +19,18 @@ runtime component. │ # CC-BY-SA-4.0; individual notes carry │ # their own licence at Zenodo-deposit time └── .github/ # CI wrappers (governance, security scan) -``` +.... -## The invariant +=== The invariant Every note listed in the README resolves to a real, citable Zenodo record. If that link breaks, the repo has failed at its one job. -## Publishing flow +=== Publishing flow -There is no runtime to diagram; the only "flow" is authorial: +There is no runtime to diagram; the only "`flow`" is authorial: -``` +.... draft note (.md [+ .typ -> .pdf]) | v @@ -44,16 +39,16 @@ draft note (.md [+ .typ -> .pdf]) v Zenodo deposit (direct API today; GitHub Release once the Zenodo-GitHub integration is enabled — see README § Zenodo archiving) -``` +.... -## Out of scope +=== Out of scope * No source code, package, or binary is built or shipped from this repo. * No API, service, or CLI. * No automated test suite — there is no code to exercise. -## See also +=== See also -* [docs/usage.adoc](docs/usage.adoc) — how to cite a note. -* [docs/contributing.adoc](docs/contributing.adoc) — how to add a new note. -* [docs/decisions/](docs/decisions/) — ADRs, historical record of why this shape. +* docs/usage.adoc — how to cite a note. +* docs/contributing.adoc — how to add a new note. +* docs/decisions/ — ADRs, historical record of why this shape. diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..bfed7b6 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,32 @@ +== Changelog + +All notable changes to `+technical-notes+` will be documented in this +file. + +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. + +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] + +==== Fixed + +* fix(ci): sync hypatia-scan.yml to canonical (413: +env.HOME+Phase-2+SARIF) (#1) + +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index eca3ce3..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,31 +0,0 @@ - - -# Changelog - -All notable changes to `technical-notes` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Fixed - -- fix(ci): sync hypatia-scan.yml to canonical (413: env.HOME+Phase-2+SARIF) (#1) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..d5c219d --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,52 @@ +== Contributing to technical-notes + +Thanks for your interest. This repository follows the Hyperpolymath +estate standards defined in +https://github.com/hyperpolymath/standards[hyperpolymath/standards]. + +=== Licence + +This project is licensed under *MPL-2.0*. By contributing you agree that +your contributions are licensed under the same terms. Every source file +carries an `+SPDX-License-Identifier+` header; keep it when editing, and +add one to any new file. + +=== Development environment + +A pinned dev shell is provided: + +[source,sh] +---- +nix develop # toolchain: git +---- + +Estate policy is Guix primary / Nix fallback; this repo currently ships +the Nix fallback. A `+guix.scm+` is welcome if you prefer the primary +tier. + +=== Language policy + +The estate restricts which languages may be used. In particular Python, +Go, TypeScript, ReScript, V-lang, Java/Kotlin, Swift and Makefiles are +*not* accepted in new code; AffineScript, Rust/SPARK, Zig, Deno, Gleam, +Elixir, Haskell, Idris2, Agda, Julia and OCaml are. CI enforces this, so +check the policy in `+hyperpolymath/standards+` before introducing a new +language. + +=== Documentation format + +Docs are AsciiDoc (`+.adoc+`) by default, including `+README.adoc+`. The +GitHub-required community-health files stay Markdown: `+SECURITY.md+`, +`+CONTRIBUTING.md+`, `+CODE_OF_CONDUCT.md+`, `+CHANGELOG.md+`. Do not +add a `+.md+` duplicate of a doc that already exists as `+.adoc+`. + +=== Pull requests + +[arabic] +. Branch from `+main+` — do not push to `+main+` directly; branch +protection requires review and passing checks. +. Keep the change focused, and explain _why_ in the PR body. +. Make sure governance CI is green. It checks documentation presence, +packaging policy, secrets, licence consistency and workflow security. +. Security issues: follow `+SECURITY.md+` — report privately, never in a +public issue. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 65a4943..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,50 +0,0 @@ - - - -# Contributing to technical-notes - -Thanks for your interest. This repository follows the Hyperpolymath estate -standards defined in [hyperpolymath/standards](https://github.com/hyperpolymath/standards). - -## Licence - -This project is licensed under **MPL-2.0**. By contributing you agree that -your contributions are licensed under the same terms. Every source file -carries an `SPDX-License-Identifier` header; keep it when editing, and add -one to any new file. - -## Development environment - -A pinned dev shell is provided: - -```sh -nix develop # toolchain: git -``` - -Estate policy is Guix primary / Nix fallback; this repo currently ships the -Nix fallback. A `guix.scm` is welcome if you prefer the primary tier. - -## Language policy - -The estate restricts which languages may be used. In particular Python, Go, -TypeScript, ReScript, V-lang, Java/Kotlin, Swift and Makefiles are **not** -accepted in new code; AffineScript, Rust/SPARK, Zig, Deno, Gleam, Elixir, -Haskell, Idris2, Agda, Julia and OCaml are. CI enforces this, so check the -policy in `hyperpolymath/standards` before introducing a new language. - -## Documentation format - -Docs are AsciiDoc (`.adoc`) by default, including `README.adoc`. The -GitHub-required community-health files stay Markdown: `SECURITY.md`, -`CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `CHANGELOG.md`. Do not add a `.md` -duplicate of a doc that already exists as `.adoc`. - -## Pull requests - -1. Branch from `main` — do not push to `main` directly; branch protection - requires review and passing checks. -2. Keep the change focused, and explain *why* in the PR body. -3. Make sure governance CI is green. It checks documentation presence, - packaging policy, secrets, licence consistency and workflow security. -4. Security issues: follow `SECURITY.md` — report privately, never in a - public issue. diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..2815c24 --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,44 @@ +== Governance + +`+technical-notes+` is a single-maintainer repository in the +`+hyperpolymath+` estate. There is no multi-maintainer or RFC process +here; estate-wide policy lives in +https://github.com/hyperpolymath/standards[`+hyperpolymath/standards+`]. + +=== Maintainer + +See link:MAINTAINERS[`+MAINTAINERS+`] for who currently maintains this +repo. + +=== Decision making + +The maintainer accepts, revises, or declines contributions directly. A +non-trivial process change — how notes are drafted, versioned, or +archived — is recorded as an ADR in +link:docs/decisions/[`+docs/decisions/+`] rather than decided ad hoc. + +=== Licensing + +* Repository tooling and process documentation: MPL-2.0 or CC-BY-SA-4.0 +per the SPDX header on each file (see `+LICENSE+` / `+LICENSES/+`). +* Each published note carries its own licence, set at Zenodo-deposit +time and recorded in that note’s Zenodo metadata (see the root +`+README.md+` § Licence). + +=== CI-enforced governance + +SPDX-header presence, licence consistency, secrets scanning, and +workflow security are enforced by the shared reusable workflow in +`+hyperpolymath/standards+`; see +link:.github/workflows/governance.yml[`+.github/workflows/governance.yml+`] +and +link:.github/workflows/hypatia-scan.yml[`+.github/workflows/hypatia-scan.yml+`]. + +=== Communication + +* *Issues*: bugs or gaps in this repo — broken DOI links, wrong +citations, process gaps. +* *Pull requests*: proposed changes; see +link:CONTRIBUTING.md[`+CONTRIBUTING.md+`]. +* *Security*: follow estate policy in `+hyperpolymath/standards+` — do +not file security-relevant findings as public issues. diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index a7f14c9..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,49 +0,0 @@ - - -# Governance - -`technical-notes` is a single-maintainer repository in the -`hyperpolymath` estate. There is no multi-maintainer or RFC process -here; estate-wide policy lives in -[`hyperpolymath/standards`](https://github.com/hyperpolymath/standards). - -## Maintainer - -See [`MAINTAINERS`](MAINTAINERS) for who currently maintains this repo. - -## Decision making - -The maintainer accepts, revises, or declines contributions directly. -A non-trivial process change — how notes are drafted, versioned, or -archived — is recorded as an ADR in -[`docs/decisions/`](docs/decisions/) rather than decided ad hoc. - -## Licensing - -* Repository tooling and process documentation: MPL-2.0 or - CC-BY-SA-4.0 per the SPDX header on each file (see `LICENSE` / - `LICENSES/`). -* Each published note carries its own licence, set at Zenodo-deposit - time and recorded in that note's Zenodo metadata (see the root - `README.md` § Licence). - -## CI-enforced governance - -SPDX-header presence, licence consistency, secrets scanning, and -workflow security are enforced by the shared reusable workflow in -`hyperpolymath/standards`; see -[`.github/workflows/governance.yml`](.github/workflows/governance.yml) -and -[`.github/workflows/hypatia-scan.yml`](.github/workflows/hypatia-scan.yml). - -## Communication - -* **Issues**: bugs or gaps in this repo — broken DOI links, wrong - citations, process gaps. -* **Pull requests**: proposed changes; see - [`CONTRIBUTING.md`](CONTRIBUTING.md). -* **Security**: follow estate policy in `hyperpolymath/standards` — - do not file security-relevant findings as public issues. diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..367c265 --- /dev/null +++ b/README.adoc @@ -0,0 +1,37 @@ +== technical-notes + +Citable short technical notes and observations — AI accountability, +agent behaviour, software engineering. Each note is archived on +https://zenodo.org/[Zenodo] with a DOI. + +=== Notes + +[width="100%",cols="14%,12%,41%,33%",options="header",] +|=== +|Note |Date |Cite (concept DOI) |Latest version +|link:agent-self-review-precommit.md[Pre-execution self-review catching +a self-introduced state-threading defect in an autonomous +code-remediation agent] (link:agent-self-review-precommit.pdf[PDF]) +|2026-05-16 +|https://doi.org/10.5281/zenodo.20245468[10.5281/zenodo.20245468] |v2 — +https://doi.org/10.5281/zenodo.20246057[10.5281/zenodo.20246057] +|=== + +____ +Cite the *concept DOI* (`+10.5281/zenodo.20245468+`) — it always +resolves to the latest version. v1 = `+10.5281/zenodo.20245469+`. +____ + +=== Zenodo archiving + +This repo is intended to be connected to the Zenodo–GitHub integration +(Zenodo → _GitHub_ settings → enable this repository). After that, +*every GitHub Release* auto-deposits a new version, grouped under a +single _concept DOI_ so versions stay citable as "`latest`". The note +above was deposited directly via the Zenodo API as a standalone record +before the integration was wired; future notes (and new versions) should +go via a GitHub Release. + +=== Licence + +Content is licensed link:LICENSE[CC-BY-4.0]. diff --git a/README.md b/README.md deleted file mode 100644 index 030ab2d..0000000 --- a/README.md +++ /dev/null @@ -1,27 +0,0 @@ -# technical-notes - -Citable short technical notes and observations — AI accountability, agent -behaviour, software engineering. Each note is archived on -[Zenodo](https://zenodo.org/) with a DOI. - -## Notes - -| Note | Date | Cite (concept DOI) | Latest version | -|------|------|--------------------|----------------| -| [Pre-execution self-review catching a self-introduced state-threading defect in an autonomous code-remediation agent](agent-self-review-precommit.md) ([PDF](agent-self-review-precommit.pdf)) | 2026-05-16 | [10.5281/zenodo.20245468](https://doi.org/10.5281/zenodo.20245468) | v2 — [10.5281/zenodo.20246057](https://doi.org/10.5281/zenodo.20246057) | - -> Cite the **concept DOI** (`10.5281/zenodo.20245468`) — it always resolves to the latest version. v1 = `10.5281/zenodo.20245469`. - -## Zenodo archiving - -This repo is intended to be connected to the Zenodo–GitHub integration -(Zenodo → *GitHub* settings → enable this repository). After that, **every -GitHub Release** auto-deposits a new version, grouped under a single -*concept DOI* so versions stay citable as "latest". The note above was -deposited directly via the Zenodo API as a standalone record before the -integration was wired; future notes (and new versions) should go via a -GitHub Release. - -## Licence - -Content is licensed [CC-BY-4.0](LICENSE). diff --git a/agent-self-review-precommit.adoc b/agent-self-review-precommit.adoc new file mode 100644 index 0000000..044b09d --- /dev/null +++ b/agent-self-review-precommit.adoc @@ -0,0 +1,120 @@ +== Pre-execution self-review catching a self-introduced state-threading defect in an autonomous code-remediation agent + +*Author:* Jonathan D. A. Jewell (hyperpolymath), The Open University — +ORCID https://orcid.org/0000-0002-3078-6652[0000-0002-3078-6652] +*Agent:* Claude Code (Anthropic), model Opus 4.7 (1M context) *Date:* +2026-05-16 · *Version:* 2 · *Licence:* CC-BY-4.0 *Supplement to:* +https://github.com/hyperpolymath/hypatia/pull/264 + +=== Abstract + +During an autonomous, multi-repository security-remediation session, a +large language model (LLM) agent generated an Elixir module and—while +reviewing its own draft _prior to executing any test_—identified and +corrected a defect it had just introduced. The defect would have +silently discarded all but the first of a sequence of lifecycle +decisions, defeating the very learning substrate the module existed to +populate. We record the episode as a verifiable behavioural datapoint +relevant to the trustworthiness of autonomous infrastructure agents, and +argue that self-caught-defect events deserve treatment as first-class +agent telemetry. + +=== 1. Context + +The task was to close the GitHub code-scanning alert-lifecycle loop +across a software estate: the agent designed and implemented +`+Hypatia.ScorecardReconciler+`, a component that classifies security +findings and dismisses, fixes, or escalates them, persisting every +decision to a fingerprint-keyed registry so that a finding class +adjudicated once is never re-reasoned. The registry is the component’s +_raison d’être_: without durable accumulation, the loop cannot stop +recurring work. + +=== 2. Method + +This is an observational single-case report. The artefact and its +history are public (the pull request and its commits), so the _outcome_ +is independently inspectable. The _process_ — the model’s reasoning that +produced the correction — is reported as an observed instance and is not +claimed to be reproducible, LLM generation being non-deterministic. No +intervention prompted the review; it occurred within the agent’s normal +draft-then-review behaviour before the test runner was invoked. + +=== 3. The defect + +The first draft iterated alerts with `+Enum.map/2+` and called a _pure_ +function, `+Registry.record(reg, fp, entry)+`, whose return value — the +updated registry map — was discarded: + +[source,elixir] +---- +# DEFECTIVE DRAFT (return value discarded; all but first decision lost) +results = Enum.map(alerts, fn alert -> + ... + Registry.record(reg, fp, %{...}) # pure; result thrown away + %{alert: number, fp: fp, action: action} +end) + +# CORRECTED (registry threaded via map_reduce) +{results, reg} = Enum.map_reduce(alerts, reg0, fn alert, reg_acc -> + ... + reg_acc = Registry.record(reg_acc, fp, %{...}) + {%{alert: number, fp: fp, action: action}, reg_acc} +end) +---- + +In a language with immutable data structures, discarding the return of a +pure accumulator is a classic, easily-missed error. The correction was +made before any test executed; a regression test (registry round-trip) +was added. The final suite reported 47 of 47 tests passing. + +=== 4. Discussion + +For agents granted authority to act autonomously on infrastructure — +here, dismissing and fixing security alerts across an organisation — the +property that determines whether the loop can run without continuous +human (and monetary) supervision is precisely _pre-execution detection +of self-introduced state-handling errors_. Tests would likely have +caught this defect; the salient point is that it was caught _earlier and +unprompted_, during self-review, which is the cheaper and more scalable +control. This aligns with long-standing software-engineering evidence +that defect cost rises sharply with detection latency [1], and with the +software-inspection literature showing structured review removes defects +that escape later phases [2]. It also bears on AI-safety arguments that +oversight of capable, acting systems should be legible and continuous +rather than terminal [3, 4]. We therefore suggest that +self-caught-defect events be surfaced as first-class agent telemetry, +not left implicit in final diffs, so that the _rate_ and _kind_ of such +catches can inform how much autonomy a given loop warrants. + +=== 5. Limitations + +A single, non-adversarial, non-reproducible observation. It demonstrates +existence, not frequency or reliability; it cannot support claims about +how often comparable agents catch comparable defects. No tool or harness +malfunction occurred; the surrounding system behaved correctly +throughout. + +=== 6. Data availability + +The corrected module, its history, and the regression test are public at +`+hyperpolymath/hypatia+` pull request #264. + +=== References + +[1] B. W. Boehm, _Software Engineering Economics_. Prentice-Hall, 1981. + +[2] M. E. Fagan, "`Design and code inspections to reduce errors in +program development,`" _IBM Systems Journal_, vol. 15, no. 3, +pp. 182–211, 1976. + +[3] D. Amodei, C. Olah, J. Steinhardt, P. Christiano, J. Schulman, and +D. Mané, "`Concrete problems in AI safety,`" arXiv:1606.06565, 2016. + +[4] S. Russell, _Human Compatible: Artificial Intelligence and the +Problem of Control_. Viking, 2019. + +=== Statement + +Reported in the interest of public accountability for autonomous AI +systems. We are all responsible for a better world. diff --git a/agent-self-review-precommit.md b/agent-self-review-precommit.md deleted file mode 100644 index db04479..0000000 --- a/agent-self-review-precommit.md +++ /dev/null @@ -1,114 +0,0 @@ -# Pre-execution self-review catching a self-introduced state-threading defect in an autonomous code-remediation agent - -**Author:** Jonathan D. A. Jewell (hyperpolymath), The Open University — ORCID [0000-0002-3078-6652](https://orcid.org/0000-0002-3078-6652) -**Agent:** Claude Code (Anthropic), model Opus 4.7 (1M context) -**Date:** 2026-05-16 · **Version:** 2 · **Licence:** CC-BY-4.0 -**Supplement to:** https://github.com/hyperpolymath/hypatia/pull/264 - -## Abstract - -During an autonomous, multi-repository security-remediation session, a large -language model (LLM) agent generated an Elixir module and—while reviewing its -own draft *prior to executing any test*—identified and corrected a defect it -had just introduced. The defect would have silently discarded all but the -first of a sequence of lifecycle decisions, defeating the very learning -substrate the module existed to populate. We record the episode as a -verifiable behavioural datapoint relevant to the trustworthiness of -autonomous infrastructure agents, and argue that self-caught-defect events -deserve treatment as first-class agent telemetry. - -## 1. Context - -The task was to close the GitHub code-scanning alert-lifecycle loop across a -software estate: the agent designed and implemented -`Hypatia.ScorecardReconciler`, a component that classifies security findings -and dismisses, fixes, or escalates them, persisting every decision to a -fingerprint-keyed registry so that a finding class adjudicated once is never -re-reasoned. The registry is the component's *raison d'être*: without -durable accumulation, the loop cannot stop recurring work. - -## 2. Method - -This is an observational single-case report. The artefact and its history -are public (the pull request and its commits), so the *outcome* is -independently inspectable. The *process* — the model's reasoning that -produced the correction — is reported as an observed instance and is not -claimed to be reproducible, LLM generation being non-deterministic. No -intervention prompted the review; it occurred within the agent's normal -draft-then-review behaviour before the test runner was invoked. - -## 3. The defect - -The first draft iterated alerts with `Enum.map/2` and called a *pure* -function, `Registry.record(reg, fp, entry)`, whose return value — the updated -registry map — was discarded: - -```elixir -# DEFECTIVE DRAFT (return value discarded; all but first decision lost) -results = Enum.map(alerts, fn alert -> - ... - Registry.record(reg, fp, %{...}) # pure; result thrown away - %{alert: number, fp: fp, action: action} -end) - -# CORRECTED (registry threaded via map_reduce) -{results, reg} = Enum.map_reduce(alerts, reg0, fn alert, reg_acc -> - ... - reg_acc = Registry.record(reg_acc, fp, %{...}) - {%{alert: number, fp: fp, action: action}, reg_acc} -end) -``` - -In a language with immutable data structures, discarding the return of a pure -accumulator is a classic, easily-missed error. The correction was made before -any test executed; a regression test (registry round-trip) was added. The -final suite reported 47 of 47 tests passing. - -## 4. Discussion - -For agents granted authority to act autonomously on infrastructure — here, -dismissing and fixing security alerts across an organisation — the property -that determines whether the loop can run without continuous human (and -monetary) supervision is precisely *pre-execution detection of -self-introduced state-handling errors*. Tests would likely have caught this -defect; the salient point is that it was caught *earlier and unprompted*, -during self-review, which is the cheaper and more scalable control. This -aligns with long-standing software-engineering evidence that defect cost -rises sharply with detection latency [1], and with the software-inspection -literature showing structured review removes defects that escape later -phases [2]. It also bears on AI-safety arguments that oversight of capable, -acting systems should be legible and continuous rather than terminal [3, 4]. -We therefore suggest that self-caught-defect events be surfaced as -first-class agent telemetry, not left implicit in final diffs, so that the -*rate* and *kind* of such catches can inform how much autonomy a given loop -warrants. - -## 5. Limitations - -A single, non-adversarial, non-reproducible observation. It demonstrates -existence, not frequency or reliability; it cannot support claims about how -often comparable agents catch comparable defects. No tool or harness -malfunction occurred; the surrounding system behaved correctly throughout. - -## 6. Data availability - -The corrected module, its history, and the regression test are public at -`hyperpolymath/hypatia` pull request #264. - -## References - -[1] B. W. Boehm, *Software Engineering Economics*. Prentice-Hall, 1981. - -[2] M. E. Fagan, "Design and code inspections to reduce errors in program -development," *IBM Systems Journal*, vol. 15, no. 3, pp. 182–211, 1976. - -[3] D. Amodei, C. Olah, J. Steinhardt, P. Christiano, J. Schulman, and -D. Mané, "Concrete problems in AI safety," arXiv:1606.06565, 2016. - -[4] S. Russell, *Human Compatible: Artificial Intelligence and the Problem -of Control*. Viking, 2019. - -## Statement - -Reported in the interest of public accountability for autonomous AI systems. -We are all responsible for a better world. diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..6b4fde1 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — technical-notes — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+MEDIUM+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+CC-BY-4.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+CC+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |27 +|`+docs/+` files |0 +|`+docs/+` LoC |0 +|CHANGELOG.md |N +|CONTRIBUTING.md |N +|CODE_OF_CONDUCT.md |N +|SECURITY.md |N +|Severity |`+MEDIUM+` +|=== + +*Recommended next move:* introduce a `+docs/+` directory. The README at +27 lines has likely grown to do the work of `+docs/+` — split it into a +thin README + `+docs/architecture.md+`, `+docs/usage.md+`, etc. +Heavy-wiki exemplars to copy from: `+affinescript+`, `+boj-server+`, +`+echidna+`, `+hypatia+`. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index 5e38d54..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — technical-notes — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `MEDIUM`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `CC-BY-4.0` | -| Manifest licence | `NONE` | -| Body classifier | `CC` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 27 | -| `docs/` files | 0 | -| `docs/` LoC | 0 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | N | -| CODE_OF_CONDUCT.md | N | -| SECURITY.md | N | -| Severity | `MEDIUM` | - -**Recommended next move:** introduce a `docs/` directory. The README at 27 lines has likely grown to do the work of `docs/` — split it into a thin README + `docs/architecture.md`, `docs/usage.md`, etc. Heavy-wiki exemplars to copy from: `affinescript`, `boj-server`, `echidna`, `hypatia`. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer.