diff --git a/.machine_readable/descriptiles/STATE.a2ml b/.machine_readable/descriptiles/STATE.a2ml index 24d69e0..3fa3f6b 100644 --- a/.machine_readable/descriptiles/STATE.a2ml +++ b/.machine_readable/descriptiles/STATE.a2ml @@ -7,7 +7,7 @@ project = "oikosbot" version = "0.1.0-dev" last-updated = "2026-09-26" status = "active" -session = "2026-08-07 documentation + debt audit: DEBT.adoc written (licence/docs/code/proof/CI-CD, every item evidenced); removed an UNEARNED OpenSSF Best Practices badge (API returns empty — never registered); deleted ARCHITECTURE.md and GOVERNANCE.md (generic boilerplate describing separate src/ and tests/ directories this repo does not have, shadowing the real .adoc versions); deleted orphaned LICENSES/AGPL-3.0-or-later.txt (no file declares it); fixed docs/README.adoc's DUPLICATED SPDX header (MPL-2.0 on line 1 shadowing CC-BY-SA-4.0 on line 2 — a doc licensed as code, and a class of defect that passes the presence check while asserting the wrong licence); ARCHITECTURE.adoc banner-flagged as TARGET design with each unbuilt component named; tech-debt-2026-05-26.adoc marked superseded; wiki built out from a one-line stub; repo description and topics set. Prior session 2026-08-03/04 estate economics round one: #60 merged (oikosbot-telemetry/-capability/-dea + estate CLI), oikosbot-estate snapshot repo created, #65 in review (path-keyed gate detection). Prior: 2026-07-28 generation-1 go-live: Pareto engine made executable (#42 — crates/oikosbot-pareto: ε-tolerant dominance, normalized weighted frontier, base-vs-head verdicts with confidence gating, oikosbot compare, SARIF pareto_* properties, EconScore composition per ARCHITECTURE); .oikos.yml --config + auto-discovery (estate configs + governance flag now real); push-email-notify removed (dual-use ruling); publish-image root-caused to GHCR package access (permission_denied: write_package — owner grant, Containerfile verified sound via podman); composite action.yml + docs/COMPARISON-climate-warrior.adoc. Rulings: Action-mode first then App; NO interim listener (upstream AffineScript Http::Server instead); advisor + machine-checked trade-offs; Scallop replaces DeepProbLog. Prior session: 2026-06-21 close-out of the post-extraction work: fleet bridge → BotId::Oikosbot + ReScript-era containers removed (#5); finding taxonomy in NEUROSYM.a2ml [finding-taxonomy] + policies/finding_taxonomy.ecl (#9); robot-repo-automaton build fix + Rust build/test/clippy CI gate (gitbot-fleet); stale-identity sweep across SECURITY/CLAUDE/META (#11); standards reusable-workflow pin refresh (#13); LICENSE dual-SPDX MPL-2.0 + CC-BY-SA-4.0, SECURITY.md finalized (reporting → j.d.a.jewell@open.ac.uk), redundant trufflehog job dropped (#14); added docs/README.adoc documentation map. Open follow-ups: #12 (taxonomy vocab reconciliation), #16 (developer+maintainer docs + README split), #17 (end-user docs), #18 (taxonomy tags through Finding types). Session 2026-09-26 (branch arena/01a0dad6-oikosbot): two long-standing red checks root-caused and fixed — Hypatia's single high/critical was research_extensions RE008 on dependabot-automerge.yml (github.actor identity check; PR-author gate retained), and Publish Image's exit 101 was an MSRV drift (tree-sitter 0.27.0 needs Rust 1.90/edition 2024 vs rust:1.88-slim; builder now rust:1-slim). #48 calibration wiring landed (see calibration-wiring and enforcement-inert). Debt register updated for the resolved items; docs delivered: docs/usage.adoc, docs/ci-runbook.adoc, per-crate READMEs, analyzers/code-haskell/README.adoc. NOT verified in CI by the author (no Rust/Haskell/Elixir toolchain in the sandbox): verification means the PR's own CI run plus, for the image, a successful Publish Image on main." +session = "2026-08-07 documentation + debt audit: DEBT.adoc written (licence/docs/code/proof/CI-CD, every item evidenced); removed an UNEARNED OpenSSF Best Practices badge (API returns empty — never registered); deleted ARCHITECTURE.md and GOVERNANCE.md (generic boilerplate describing separate src/ and tests/ directories this repo does not have, shadowing the real .adoc versions); deleted orphaned LICENSES/AGPL-3.0-or-later.txt (no file declares it); fixed docs/README.adoc's DUPLICATED SPDX header (MPL-2.0 on line 1 shadowing CC-BY-SA-4.0 on line 2 — a doc licensed as code, and a class of defect that passes the presence check while asserting the wrong licence); ARCHITECTURE.adoc banner-flagged as TARGET design with each unbuilt component named; tech-debt-2026-05-26.adoc marked superseded; wiki built out from a one-line stub; repo description and topics set. Prior session 2026-08-03/04 estate economics round one: #60 merged (oikosbot-telemetry/-capability/-dea + estate CLI), oikosbot-estate snapshot repo created, #65 in review (path-keyed gate detection). Prior: 2026-07-28 generation-1 go-live: Pareto engine made executable (#42 — crates/oikosbot-pareto: ε-tolerant dominance, normalized weighted frontier, base-vs-head verdicts with confidence gating, oikosbot compare, SARIF pareto_* properties, EconScore composition per ARCHITECTURE); .oikos.yml --config + auto-discovery (estate configs + governance flag now real); push-email-notify removed (dual-use ruling); publish-image root-caused to GHCR package access (permission_denied: write_package — owner grant, Containerfile verified sound via podman); composite action.yml + docs/COMPARISON-climate-warrior.adoc. Rulings: Action-mode first then App; NO interim listener (upstream AffineScript Http::Server instead); advisor + machine-checked trade-offs; Scallop replaces DeepProbLog. Prior session: 2026-06-21 close-out of the post-extraction work: fleet bridge → BotId::Oikosbot + ReScript-era containers removed (#5); finding taxonomy in NEUROSYM.a2ml [finding-taxonomy] + policies/finding_taxonomy.ecl (#9); robot-repo-automaton build fix + Rust build/test/clippy CI gate (gitbot-fleet); stale-identity sweep across SECURITY/CLAUDE/META (#11); standards reusable-workflow pin refresh (#13); LICENSE dual-SPDX MPL-2.0 + CC-BY-SA-4.0, SECURITY.md finalized (reporting → j.d.a.jewell@open.ac.uk), redundant trufflehog job dropped (#14); added docs/README.adoc documentation map. Open follow-ups: #12 (taxonomy vocab reconciliation), #16 (developer+maintainer docs + README split), #17 (end-user docs), #18 (taxonomy tags through Finding types). Session 2026-09-26 (branch arena/01a0dad6-oikosbot): two long-standing red checks root-caused and fixed — Hypatia's single high/critical was research_extensions RE008 on dependabot-automerge.yml (github.actor identity check; PR-author gate retained), and Publish Image's exit 101 was an MSRV drift (tree-sitter 0.27.0 needs Rust 1.90/edition 2024 vs rust:1.88-slim; builder now rust:1-slim). #48 calibration wiring landed (see calibration-wiring and enforcement-inert). Debt register updated for the resolved items; docs delivered: docs/usage.adoc, docs/ci-runbook.adoc, per-crate READMEs, analyzers/code-haskell/README.adoc. NOT verified in CI by the author (no Rust/Haskell/Elixir toolchain in the sandbox): verification means the PR's own CI run plus, for the image, a successful Publish Image on main. Also this session: DEBT.adoc re-verified against the tree — six entries whose fixes had already landed (orphaned AGPL licence text, unheaded GOVERNANCE.md, the ARCHITECTURE.md/GOVERNANCE.md boilerplate pair, the unannotated ARCHITECTURE.adoc, the wiki stub, the dormant push-email-notify.yml) are now marked resolved with evidence; the wiki is recorded as CLAIMED not verified because wiki pages are not in the repository tree; licence identifier counts re-measured (159 MPL-2.0 / 65 CC-BY-SA-4.0 occurrences). Local verification that WAS possible: every changed .rs file parses clean under the tree-sitter-rust grammar (no ERROR nodes); all 12 AnalysisResult struct literals in the workspace carry resource_range; the check_gate.rs fixtures were simulated through a port of the analyser's own logic (complexity, loop depth, pattern detection, calibration rows, Pareto verdict) and reproduce the asserted verdicts; tools/ci/linter-verify.sh passes all four steps." [project-context] name = "OikosBot" diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index cae6ca7..f723f87 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -17,6 +17,18 @@ https://semver.org/spec/v2.0.0.html[Semantic Versioning]. ==== Added +* docs: `+DEBT.adoc+` re-verified against the tree. Six entries whose fixes had + already landed were still listed as open — the orphaned `+LICENSES/AGPL-3.0-or-later.txt+`, + the unheaded `+GOVERNANCE.md+`, the boilerplate `+ARCHITECTURE.md+`/ + `+GOVERNANCE.md+` pair, the unannotated `+ARCHITECTURE.adoc+`, the one-line + wiki stub, and the dormant `+push-email-notify.yml+`. Each is now marked + resolved with its date and evidence; the wiki is recorded as *claimed* + rather than verified because wiki pages are not part of the repository tree. + The licence-identifier counts were re-measured (159 MPL-2.0 / 65 CC-BY-SA-4.0 + occurrences), and the #16/#17 entry now names what the 2026-09-26 + documentation pass delivered. `+ROADMAP.adoc+` follows: candidate (B) is + marked landed, and "policy rules in Datalog and DeepProbLog" no longer claims + the retired DeepProbLog asset. * feat(analysis): wire the calibration framework into the analyser (issue #48). `Analyzer::estimate_resources()` maps a detected pattern onto an `+OperationKind+` via the new `+calibration::operation_for_pattern+` and diff --git a/DEBT.adoc b/DEBT.adoc index bf990ad..00f1ff2 100644 --- a/DEBT.adoc +++ b/DEBT.adoc @@ -27,8 +27,8 @@ Severity is about *consequence*, not effort: |=== | Area | Worst | One-line -| <> | HYGIENE | One orphaned licence text; one doc missing its SPDX header. -| <> | STRUCTURAL | Two boilerplate files describe a directory layout this repo does not have; `ARCHITECTURE.adoc` specifies components that were never built. +| <> | HYGIENE | Nothing open. The orphaned AGPL text, the unheaded `GOVERNANCE.md` and the duplicated header in `docs/README.adoc` are all gone (verified against the tree, 2026-09-26). +| <> | HYGIENE | The boilerplate `.md` pair and the unannotated `ARCHITECTURE.adoc` are gone. What remains is `config/oikos.yaml`'s ASPIRATIONAL blocks, the #12 taxonomy collision, and #16/#17 still only partly addressed. | <> | BLOCKING | Unrecognised code still derives every resource axis from one integer, so its Pareto frontier is a one-dimensional sort. Recognised patterns are now calibrated (2026-09-26). | <> | BLOCKING | The Datalog policy engine has never executed; the Eclexia policy backend matches on filenames and never reads the files. | <> | BLOCKING | Four phantom required contexts block every pull request, so every merge needs `--admin`. The two long-standing red checks are fixed; the consumer fleet cannot run until each repo ships a lockfile. @@ -38,22 +38,18 @@ Severity is about *consequence*, not effort: == Licence debt The scheme itself is sound and consistently applied: **MPL-2.0 for code, -CC-BY-SA-4.0 for documentation**, 78 and 29 declarations respectively -(`grep -rhoP "SPDX-License-Identifier: \K[A-Za-z0-9.+-]+"`). +CC-BY-SA-4.0 for documentation**, 159 and 65 identifier occurrences respectively +(`grep -rhoP "SPDX-License-Identifier: \K[A-Za-z0-9.+-]+"`, re-counted +2026-09-26 against the current tree; the raw total includes two headers quoted +inside `docs/superpowers/plans/2026-08-03-estate-economics-round-one.adoc`, +which teaches the convention by example). No third licence is declared anywhere +in the tree. [cols="1,4"] |=== -| `HYGIENE` | *`LICENSES/AGPL-3.0-or-later.txt` is orphaned.* No file in the -repository declares `SPDX-License-Identifier: AGPL-3.0-or-later`; the only -textual occurrence of "AGPL" outside `LICENSES/` is a *quotation of another -repo's* header inside `docs/superpowers/specs/`. A REUSE-conformant tree -carries licence texts only for licences actually in use, so this reads as an -unused licence. *Fix:* delete the file. *Risk if wrong:* if a future file -genuinely needs AGPL, re-add it then. - -| `HYGIENE` | *`GOVERNANCE.md` carries no SPDX header at all* — see -<>, where it is slated for deletion as boilerplate. Every other document -in the tree has one. +| — | *Resolved 2026-08-07 (re-verified against the tree 2026-09-26):* *`LICENSES/AGPL-3.0-or-later.txt` was orphaned.* No file declared the AGPL identifier, so a REUSE-conformant tree should not carry its text. The file is absent from both the working tree and the base commit (`git ls-tree -r 7781489 -- LICENSES/` → only `CC-BY-SA-4.0.txt`, `MPL-2.0.txt`). The only remaining "AGPL" strings are a prohibition in `.machine_readable/descriptiles/AGENTIC.a2ml` ("Never use AGPL license (use MPL-2.0)"), this register, and a quotation of another repo's header in `docs/superpowers/specs/`. Note the identifier itself is deliberately *not* restated verbatim in this entry: a quoted `SPDX-License-Identifier:` line inside a document is indistinguishable from a real declaration to `grep`, and this register has already recorded that class of defect once (see the duplicated-header entry above). + +| — | *Resolved 2026-08-07 (re-verified 2026-09-26):* *`GOVERNANCE.md` carried no SPDX header at all.* The file was deleted as boilerplate (see <>); the surviving `GOVERNANCE.adoc` carries `SPDX-License-Identifier: CC-BY-SA-4.0` on line 1, as every other document does. | `HYGIENE` | *`docs/README.adoc` was mis-licensed by a duplicated header.* It carried **two** conflicting identifiers — `MPL-2.0` on line 1 and @@ -75,33 +71,11 @@ invisible: a correct header in the wrong position silently fails the gate. [cols="1,4"] |=== -| `STRUCTURAL` | *`ARCHITECTURE.md` is generic boilerplate that contradicts the -repository.* It documents a `src/ tests/ scripts/ config/` layout; this repo is -a Cargo workspace whose code lives in `crates/`. It has no SPDX header, and it -shadows the real 33 KB `ARCHITECTURE.adoc` — a reader who opens the `.md` -learns nothing true. *Fix:* delete. Template rot, not authored content. - -| `STRUCTURAL` | *`GOVERNANCE.md` is the same defect* — generic prose -("governed by the following principles and structures") duplicating the real, -SPDX-headed `GOVERNANCE.adoc`. *Fix:* delete. - -| `STRUCTURAL` | *`ARCHITECTURE.adoc` specifies components that do not exist.* -Measured against the tree: -+ -* §196 specifies an *OCaml documentation analyzer* at `/analyzers/docs-ocaml/`. - `analyzers/` contains only `code-haskell`. -* §424 lists the policy engine as *"Python + Datalog"*. Python is banned by the - language policy, and the 2026-07-28 ruling retargeted the engine to Scallop - (Rust). The document was never updated. -* §29 describes four bot roles — *consultant, advisor, regulator, and policy - developer*. `crates/oikosbot-cli/src/config.rs` implements three; there is no - `policy developer` mode. -* §121–§358 describe a *Praxis Loop* and DeepProbLog inference that are not - implemented. -+ -*Fix:* mark it explicitly as *target design, not current state*, and annotate -each unbuilt component inline — the cheapest honest option, given it is a real -design document rather than rot. +| — | *Resolved 2026-08-07 (re-verified against the tree 2026-09-26):* *`ARCHITECTURE.md` was generic boilerplate contradicting the repository.* It documented a `src/ tests/ scripts/ config/` layout while this repo is a Cargo workspace whose code lives in `crates/`, it had no SPDX header, and it shadowed the real `ARCHITECTURE.adoc`. Deleted; `ARCHITECTURE.adoc` is now the only architecture document and is banner-flagged as target design. + +| — | *Resolved 2026-08-07 (re-verified 2026-09-26):* *`GOVERNANCE.md` was the same defect* — generic prose duplicating the real, SPDX-headed `GOVERNANCE.adoc`. Deleted. + +| — | *Resolved 2026-08-07 (re-verified 2026-09-26):* *`ARCHITECTURE.adoc` specified components that do not exist.* The document now opens with a `[WARNING]` block — "*This is the TARGET design, not the current state*" — that names each unbuilt component inline: the OCaml documentation analyzer (absent; `analyzers/` holds only `code-haskell`), the superseded "Python + Datalog" policy-engine line (Python is banned; the 2026-07-28 ruling retargets to Scallop), the fourth `policy developer` bot role (only three modes exist in `crates/oikosbot-cli/src/config.rs`), and the Praxis Loop / DeepProbLog inference. Readers are pointed at `docs/STATUS.adoc`, `EXPLAINME.adoc` and this register for what is actually built. | `BLOCKING` | *The README carried an unearned OpenSSF Best Practices badge.* A hardcoded green `shields.io` image asserting "OpenSSF Best Practices", linked @@ -114,8 +88,12 @@ the project cannot support. *Removed in this audit.* This matches a documented estate-wide template-drift pattern; other repos should be grepped for the same badge block. -| `STRUCTURAL` | *The wiki is a one-line stub* ("Welcome to the oikosbot -wiki!"). It is enabled and indexed, so it is a discoverable dead end. +| — | *Claimed resolved 2026-08-07; not re-verified here.* *The wiki was a +one-line stub* ("Welcome to the oikosbot wiki!") while enabled and indexed, so +it was a discoverable dead end. `.machine_readable/descriptiles/STATE.a2ml` +records that the wiki was "built out from a one-line stub" in that session. +Wiki pages are not part of the repository tree, so this entry could not be +confirmed from the checkout and is recorded as claimed rather than verified. | `HYGIENE` | *Taxonomy vocabulary collision* (issue https://github.com/hyperpolymath/oikosbot/issues/12[#12]): @@ -131,8 +109,13 @@ https://github.com/hyperpolymath/oikosbot/pull/59[#59] by marking each block | `HYGIENE` | *Open docs issues* https://github.com/hyperpolymath/oikosbot/issues/16[#16] (split README into a docs tree) and https://github.com/hyperpolymath/oikosbot/issues/17[#17] -(end-user guide: interpreting findings, SARIF, policy customisation) remain -open and are only partly addressed by `docs/README.adoc`. +(end-user guide: interpreting findings, SARIF, policy customisation) are +substantially addressed but not closed. `docs/README.adoc` is now a +documentation map, and 2026-09-26 added `docs/usage.adoc` (interpreting +findings, SARIF fields, confidence levels, policy customisation), +`docs/ci-runbook.adoc`, a per-crate `README.adoc` set and +`analyzers/code-haskell/README.adoc`. What is still missing is an issue-level +walkthrough for a maintainer triaging a specific finding. |=== [#code] @@ -423,9 +406,7 @@ https://github.com/hyperpolymath/oikosbot/pull/64[#64]. settings-level disabled state (which is invisible from the repository contents), why it is kept, and what re-enabling requires. -| `HYGIENE` | *`push-email-notify.yml` is dormant by design* but remains in the -tree; the estate's dual-use ruling calls for removing push-email workflows -except where explicitly exempted. +| — | *Resolved 2026-07-28 (re-verified against the tree 2026-09-26):* *`push-email-notify.yml` was dormant by design* while remaining in the tree, against the estate's dual-use ruling. The workflow is gone from `.github/workflows/` (15 workflows listed, none named `push-email-notify.yml`), and `STATE.a2ml` records its removal under that ruling. |=== == What is *not* debt @@ -457,3 +438,15 @@ repository for CI and issue state, and `jq` over https://github.com/hyperpolymath/oikosbot-estate[`hyperpolymath/oikosbot-estate`]. Claims sourced from earlier sessions were re-verified before being repeated here; anything that could not be re-verified was dropped rather than restated. + +Re-verified 2026-09-26 against the tree at `7781489` (origin/main) plus the +working changes on `arena/01a0dad6-oikosbot`. That pass found six entries whose +fixes had already landed but had never been marked resolved — the orphaned AGPL +licence text, the unheaded `GOVERNANCE.md`, the boilerplate `.md` pair, the +unannotated `ARCHITECTURE.adoc`, the wiki stub, and the dormant +`push-email-notify.yml`. Each is now marked resolved with the evidence and the +date it was fixed, except the wiki, whose contents are not part of the +repository tree and is therefore recorded as *claimed* rather than verified. +Two entries were corrected rather than closed: the licence-identifier counts +were re-measured, and the #16/#17 docs entry now names what the 2026-09-26 +documentation pass actually delivered. diff --git a/ROADMAP.adoc b/ROADMAP.adoc index 99e2143..25b28d7 100644 --- a/ROADMAP.adoc +++ b/ROADMAP.adoc @@ -22,7 +22,9 @@ Status legend: `done` | `in-progress` | `blocked` | `planned` * [x] Haskell analyzer scaffold at `analyzers/code-haskell/` * [x] AffineScript webhook receiver scaffold at `bot-integration-affine/` * [x] GitHub App manifest at `.github/app.yml` -* [x] Policy rules in Datalog and DeepProbLog +* [x] Policy rules in Datalog (`policy-engine/datalog/eco_rules.dl`) — a + specification the Rust dominance code conforms to; the DeepProbLog asset that + once sat beside it was retired by the 2026-07-28 ruling and deleted 2026-09-26 * [x] Bot configuration, prompt templates, and database schema assets * [x] Repository split from the Oikos DSL @@ -76,6 +78,18 @@ longer backfill. The decision criterion is reported by the pipeline itself: the independence matrix, dual stability across at least two snapshots, and telemetry coverage. **Requires snapshot #2.** +* *(B) landed 2026-09-26* — `calibration.rs` is wired into + `Analyzer::estimate_resources()`, so findings on a recognised pattern carry + `Calibrated`/`Estimated` confidence and `--check` exits 1 on an undocumented + calibrated regression (issue #48). Proven by + `crates/oikosbot-cli/tests/check_gate.rs` against the real binary. Two + consequences are recorded rather than hidden: the naive path (unrecognised + code) is still collinear and still `Estimated`, and calibrated energies are + so small that `calculate_eco_score` saturates near 100, which makes the + `check` eco-threshold gate near-vacuous — an owner ruling on the EnergyScore + scale is required. Awaiting CI verification (no Rust toolchain in the + authoring sandbox). + * [ ] *Consumer lockfile sweep (P1)* — 15 estate repositories carry `oikosbot.yml` merged and pinned, but each needs its own Actions lockfile before the workflow can start. OikosBot is installed everywhere and running