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.