HOMELAB-1730: feat(routines): LD4.8 agent-readiness score (R-24) #576

Merged

aaron merged 9 commits from plane/HOMELAB-1730-readiness into epic/LD4 2026-10-03 03:03:29 +00:00

Conversation 4 Commits 9 Files changed 35 +35682 -32

aaron commented 2026-10-02 04:06:02 +00:00

Owner

Copy link

LD4.8 · agent-readiness score. Lands the already-reserved R-24 (not a new id). Brief: .rpiv/artifacts/epic-ld4/design-LD4.8-readiness.md; orchestrator rulings on HOMELAB-1730 supersede it where they differ.

Head: 8597d0e, rebased onto epic/LD4 (13 commits, incl. R-25/HOMELAB-1729 and the LD4.5a alert audit) so the PR is mergeable; the pre-rebase head reviewed was f18f3b8. Landing-review fixes: b639d1a (fan-out + budget), 2d9e34b (adapter tests), 4af920d (clean calibration target + cost evidence), 8597d0e (gofmt). Rebase conflicts were the registry/census hunks and are resolved to the merged totals: 22 corpus routines + R-24 (active, HOMELAB-1730) + R-25 (paused, HOMELAB-1729) = 24 registered, 4 active.

What is in here

Piece	File
Scoring definition (data, versioned)	routines/readiness.yaml
Strict loader (unknown probe/key/override-contradiction = refusal, with line numbers)	routines/readiness_definition.go + _test.go
The seven mechanical probes	routines/readiness_probes.go
Workflow/CI-step attribution (the SEND-437 mechanism)	routines/readiness_workflows.go
Scorer, canonical JSON report, markdown rendering, weakest-line verdict	routines/readiness.go
Digest + window-two repair-ticket refs	routines/readiness_digest.go
Signals: offline worktree / saved runs dump / live read-only Forgejo	routines/readiness_{signals,git,forgejo}.go + readiness_{forgejo,git}_test.go
Runnable mechanism	cmd/readiness
Ledger target field (additive on ld.routine.run/v1)	routines/ledger.go + _test.go
R-24 registration	routines/registry.yaml
Calibration evidence	routines/testdata/readiness-calibration.md + testdata/readiness-calibration/

Seven lines per the ruling: ci_present, ci_green, test_inventory, docs, lint, agent_context, dev_env (advisory v1). Floor: weakest line, never_below [ci_present, test_inventory], min_lines_passed 5 of 6 counted. dev_env declares counts: false and is named in floor.advisory (the loader requires the two statements to agree, not to be duplicated in one place).

Verify line 1 — calibration (scar, below-floor, clean)

Full evidence in routines/testdata/readiness-calibration.md; reports + trimmed GET /actions/runs dumps are committed so the run is re-derivable offline.

SEND-437-class — Sendrast/api-sendrast @ 968c0cb → below-floor (reproduces exactly):

line	outcome	reading
ci_present	pass	1 of 4 workflows on the gate branch main (derived from the workflows' own on: blocks)
ci_green	pass	success — newest run for the sha (ci.yml, push, main, run #552)
test_inventory	fail	207 test files: (untagged) 119/132 (90%), functional 1/1, integration 9/74 (12%)
docs	pass	52 files under docs/, 634-line README
lint	pass	.forgejo/workflows/ci.yml (matched vet) green
agent_context	fail	no AGENTS.md/CLAUDE.md/spec tree
dev_env	advisory: pass	scripts/sim_reset/sandbox/docker-compose.yml

Green gate over an invisible test class — the scar, mechanically. A blended file ratio says 90% executed; the per-class floor is what makes the invisible class visible.

CLEAN — Sendrast/sendrast-web @ aa500803 → ready (6/6). Added to routines/readiness.yaml and R-24's targets.paths per the orchestrator's calibration ruling: the Verify line needs the healthy direction, otherwise the calibration only shows the mechanism reddening a sick repo.

line	outcome	reading
ci_present	pass	1 of 2 workflow files triggers on main (.forgejo/workflows/ci.yml)
ci_green	pass	success — push run for the scored sha (ci.yml, push, main, run #552)
test_inventory	pass	151 test files, (untagged) 151/151 (100%)
docs	pass	4 files under docs/, 238-line README
lint	pass	.forgejo/workflows/ci.yml (matched lint) has a successful run
agent_context	pass	AGENTS.md at the repository root
dev_env	advisory: fail	none declared

The ruling's named repo does not exist. Homelab/lab-director-contract returns HTTP 404 on the live instance (and is absent from the token's repo list); the checkout named ~/repos/lab-director-contract is a clone of aaron/lab-director, which scores 1/6 below-floor at both f2e16ae (the contract-only state) and current main (no gate, no README, no tests — and ci_present is never_below, so no contract-only repo can pass by construction). Recorded with evidence in §4 of the calibration doc; it was not forced green and not added to the scored scope. Sendrast/sendrast-web is the clean target instead.

"Clean" side in the ruled scope — Homelab/infra-core does NOT reproduce the brief's expected verdict. At 1519dd2 (this branch's merge base): below-floor (3/6) — ci_green fails (no run exists for the merge sha; the newest live push run was a docs-build failure), docs fails (80 files under docs/ but no repo-root README.md at all), agent_context fails (no AGENTS.md; CLAUDE.md+INFRA_CONTEXT.md = partial). At the PR head b5a806a (run #568 green) the same tree is 4/6 with the same two non-CI failures. Details and the three independently checkable reasons are in the calibration doc.

Systematic finding (for the architect / window two): merge commits on live carry no gate run — the gate runs on the PR head — so every three-tier repo's latest merge revision reads as ungated. The report now names the newest gate-branch run as evidence + a finding rather than a bare "no run". The ruling already made window one REPORT-ONLY, which is exactly the window that measures how often this fires.

Homelab/prod @ f006b26 (override exercised): below-floor (2/4 counted) — override works (test_inventory/docs advisory, never_below narrowed to [ci_present], printed in the digest as neverBelowNarrowed), but ci_green (merge commit) and agent_context fail.

Cost (landing-review blocker 2)

v1 read one GET /raw/{path} per test file, so cost was linear in the repo's test count and undeclared. The fix, measured live on this branch's build:

repo	v1 (review)	now	requests	budget
Homelab/infra-core	2 m 03 s	11.9 s	7	16
Sendrast/api-sendrast	~5 m	19.0 s	6	16
Homelab/prod	28 s	9.5 s	5	16

• File() is served from the revision tarball, materialized by one GET /archive/{rev}.tar.gz; the raw endpoint is a bounded fallback only (archive disabled, gitlink). TestForgejoSignalsFileCostIsConstantInTheFileCount pins it: reading 120 files costs the same as reading 2.
• Runs reads are two filtered, bounded windows — ?head_sha=<rev> and ?head_branch=<gate>&event=push&page=1&limit=<n> — because the endpoint ignores limit without a filter and otherwise returns the whole history (612 runs / ~10 MB / ~20 s on infra-core). Both cached; RunsOnBranch reaches probeContext.runs() through the new optional BranchRunSource seam and the windows are merged by identity.
• ForgejoSignals.MaxRequests (default 16) is a hard stop that fails LOUDLY with ForgejoRequestBudgetError, so a re-introduced fan-out cannot silently spend the routine's window. The adapter refuses an unfiltered runs read outright.
• cmd/readiness prints wall time and GET count per target, so cost is observed by the run rather than by a reviewer.

Eight targets on this build is roughly two minutes of R-24's maxDurationSeconds: 900 (>7× margin).

Deviations from the brief (all deliberate, all visible)

1. Gate branch is derived, not assumed. The brief assumed default branch == gate branch. Homelab/infra-core and Homelab/prod run every gate on live and receive zero CI runs on main; scoring main would report "no run" for repos whose gate is green on every landing. Resolution order: definition override → branch most workflows trigger on (derived from primary sources) → default branch. Both three-tier repos name live explicitly in the definition as well. The digest prints the branch and its source, and the divergence from the default branch is a finding.
2. test_inventory is per-class, not blended. The brief's formula (ran_by_ci / a with packages over files) is unit-inconsistent and, applied to the real data, passes the very revision it was written to catch (go test ./... really does run 90% of api-sendrast's files). The rule implemented: a file is executed iff a gate step references its package, its -tags cover the file's build tags, and any -run filter matches a test function parsed out of the file; files are grouped by build-tag class and every class must be ≥ test_class_min_ratio. This is the brief's own -run mechanism, made to actually fire.
3. lint does not read job detail. Forgejo v14.0.3 has no /actions/runs/{id}/jobs endpoint (verified live: 404). The line uses the workflow file's own lint vocabulary plus that workflow's run status; the narrowing is stated in the definition's detail. The newest gate-branch run is read from the bounded push window (blocker-2 fix), not from the repo's whole history.
4. The corpus parity test moved by three lines. Adding a registered non-corpus routine to registry.yaml makes the reverse check ("registered but not in the corpus table") fire. It now derives the hosted 4.x set from testdata/registry-4x-shapes.yaml instead of listing it, so R-24 cannot claim an exemption the fixture does not grant. testdata/corpus-table.md is untouched (R-01…R-22 stays closed at 22); TestRealRegistryLoads expects 23.
5. R-24's targets.paths gained one entry (Sendrast/sendrast-web, the clean calibration target) on the orchestrator's calibration ruling. The definition's targets: list and the registry's authority are now asserted equal in TestRealDefinitionLoads, so they cannot drift.

Pin discipline

routines -check prints 23 routines, 4 active (R-03, R-06, R-19, R-24); TestInProcessPinsMatchTheCode is green on the new sha256 for readiness.go. Known limitation, stated rather than hidden: the mechanism is a file set (readiness_probes.go, readiness_workflows.go, readiness_{signals,git,forgejo,digest}.go + the data file readiness.yaml); the LD4.4 pin test covers one file. Editing readiness.go after registration requires re-pinning R-24 — that is the routine's own anti-drift rule, and extending the pin to the whole set is queued as a follow-up rather than smuggled into this ticket.

Shared files (minimal, as declared)

• routines/registry.yaml — my R-24 entry only (siblings own R-25 and any 4.5a entry): the reserved-ids header comment, the "active today" count, and the R-24 targets.paths addition above.
• routines/ledger.go — additive Run.Target, ValidateFor/TargetRequired, RunFilter.Target. No v2 stamp, no transport change.
• routines/registry_test.go, routines/parity_test.go, cmd/routines/main_test.go — count/parity/census adjustments (the last derives the census and active set from Registry.Census() instead of hard-coding 22/3).
• No config/ keys needed; no dispatcher/spawn changes (enforcement is HOMELAB-1857).

Window policy

emitsWork: false and RepairRefs(..., emit=false) — report-only, per the ruling. Window two flips emitsWork: true with emits: [R-07] so the readiness-repair: tickets are visible to the entropy sweep; the dedup convention (blocked_by on the epic's first builder ticket) is documented as a human/agent act today, never as enforcement.

Tests

go test -race ./... and go vet ./... green in lab-director/dispatcher. No test opens a real socket. routines/readiness_forgejo_test.go drives the live adapter against an httptest fixture and asserts the request shape (one archive request for N files, zero raw reads, filtered/bounded runs windows, the budget stop, error/redaction paths); routines/readiness_git_test.go drives the offline seam against a real temp git checkout (revision pinning, RunsFromFile decoding, the branch-window merge) plus the httptest-free fixture paths.

LD4.8 · agent-readiness score. Lands the already-reserved **R-24** (not a new id). Brief: `.rpiv/artifacts/epic-ld4/design-LD4.8-readiness.md`; orchestrator rulings on HOMELAB-1730 supersede it where they differ. Head: `8597d0e`, **rebased onto `epic/LD4`** (13 commits, incl. R-25/HOMELAB-1729 and the LD4.5a alert audit) so the PR is mergeable; the pre-rebase head reviewed was `f18f3b8`. Landing-review fixes: `b639d1a` (fan-out + budget), `2d9e34b` (adapter tests), `4af920d` (clean calibration target + cost evidence), `8597d0e` (gofmt). Rebase conflicts were the registry/census hunks and are resolved to the merged totals: 22 corpus routines + **R-24** (active, HOMELAB-1730) + **R-25** (paused, HOMELAB-1729) = 24 registered, 4 active. ## What is in here | Piece | File | |---|---| | Scoring definition (data, versioned) | `routines/readiness.yaml` | | Strict loader (unknown probe/key/override-contradiction = refusal, with line numbers) | `routines/readiness_definition.go` + `_test.go` | | The seven mechanical probes | `routines/readiness_probes.go` | | Workflow/CI-step attribution (the SEND-437 mechanism) | `routines/readiness_workflows.go` | | Scorer, canonical JSON report, markdown rendering, weakest-line verdict | `routines/readiness.go` | | Digest + window-two repair-ticket refs | `routines/readiness_digest.go` | | Signals: offline worktree / saved runs dump / live read-only Forgejo | `routines/readiness_{signals,git,forgejo}.go` + `readiness_{forgejo,git}_test.go` | | Runnable mechanism | `cmd/readiness` | | Ledger `target` field (additive on `ld.routine.run/v1`) | `routines/ledger.go` + `_test.go` | | R-24 registration | `routines/registry.yaml` | | Calibration evidence | `routines/testdata/readiness-calibration.md` + `testdata/readiness-calibration/` | Seven lines per the ruling: `ci_present`, `ci_green`, `test_inventory`, `docs`, `lint`, `agent_context`, `dev_env` (advisory v1). Floor: weakest line, `never_below [ci_present, test_inventory]`, `min_lines_passed 5` of 6 counted. `dev_env` declares `counts: false` and is named in `floor.advisory` (the loader requires the two statements to agree, not to be duplicated in one place). ## Verify line 1 — calibration (scar, below-floor, clean) Full evidence in `routines/testdata/readiness-calibration.md`; reports + trimmed `GET /actions/runs` dumps are committed so the run is re-derivable offline. **SEND-437-class — `Sendrast/api-sendrast @ 968c0cb` → `below-floor` (reproduces exactly):** | line | outcome | reading | |---|---|---| | ci_present | pass | 1 of 4 workflows on the gate branch `main` (derived from the workflows' own `on:` blocks) | | ci_green | **pass** | `success` — newest run for the sha (ci.yml, push, main, run #552) | | test_inventory | **fail** | 207 test files: `(untagged) 119/132 (90%)`, `functional 1/1`, **`integration 9/74 (12%)`** | | docs | pass | 52 files under `docs/`, 634-line README | | lint | pass | `.forgejo/workflows/ci.yml` (matched `vet`) green | | agent_context | fail | no `AGENTS.md`/`CLAUDE.md`/spec tree | | dev_env | advisory: pass | `scripts/sim_reset/sandbox/docker-compose.yml` | Green gate over an invisible test class — the scar, mechanically. A blended file ratio says 90% executed; the per-class floor is what makes the invisible class visible. **CLEAN — `Sendrast/sendrast-web @ aa500803` → `ready` (6/6).** Added to `routines/readiness.yaml` and R-24's `targets.paths` per the orchestrator's calibration ruling: the Verify line needs the healthy direction, otherwise the calibration only shows the mechanism reddening a sick repo. | line | outcome | reading | |---|---|---| | ci_present | pass | 1 of 2 workflow files triggers on `main` (`.forgejo/workflows/ci.yml`) | | ci_green | **pass** | `success` — push run for the scored sha (ci.yml, push, main, run #552) | | test_inventory | pass | 151 test files, `(untagged) 151/151 (100%)` | | docs | pass | 4 files under `docs/`, 238-line README | | lint | pass | `.forgejo/workflows/ci.yml` (matched `lint`) has a successful run | | agent_context | pass | `AGENTS.md` at the repository root | | dev_env | advisory: fail | none declared | **The ruling's named repo does not exist.** `Homelab/lab-director-contract` returns **HTTP 404** on the live instance (and is absent from the token's repo list); the checkout named `~/repos/lab-director-contract` is a clone of **`aaron/lab-director`**, which scores **1/6 `below-floor`** at both `f2e16ae` (the contract-only state) and current `main` (no gate, no README, no tests — and `ci_present` is `never_below`, so no contract-only repo can pass by construction). Recorded with evidence in §4 of the calibration doc; it was **not** forced green and **not** added to the scored scope. `Sendrast/sendrast-web` is the clean target instead. **"Clean" side in the ruled scope — `Homelab/infra-core` does NOT reproduce the brief's expected verdict.** At `1519dd2` (this branch's merge base): **`below-floor` (3/6)** — `ci_green` fails (no run exists for the merge sha; the newest `live` push run was a `docs-build` failure), `docs` fails (80 files under `docs/` but **no repo-root `README.md` at all**), `agent_context` fails (no `AGENTS.md`; `CLAUDE.md`+`INFRA_CONTEXT.md` = partial). At the PR head `b5a806a` (run #568 green) the same tree is **4/6** with the same two non-CI failures. Details and the three independently checkable reasons are in the calibration doc. **Systematic finding (for the architect / window two):** merge commits on `live` carry no gate run — the gate runs on the PR head — so every three-tier repo's latest merge revision reads as ungated. The report now names the newest gate-branch run as evidence + a finding rather than a bare "no run". The ruling already made window one REPORT-ONLY, which is exactly the window that measures how often this fires. **`Homelab/prod @ f006b26` (override exercised):** `below-floor` (2/4 counted) — override works (`test_inventory`/`docs` advisory, `never_below` narrowed to `[ci_present]`, printed in the digest as `neverBelowNarrowed`), but `ci_green` (merge commit) and `agent_context` fail. ## Cost (landing-review blocker 2) v1 read one `GET /raw/{path}` per test file, so cost was linear in the repo's test count and undeclared. The fix, measured live on this branch's build: | repo | v1 (review) | now | requests | budget | |---|---|---|---|---| | `Homelab/infra-core` | 2 m 03 s | **11.9 s** | 7 | 16 | | `Sendrast/api-sendrast` | ~5 m | **19.0 s** | 6 | 16 | | `Homelab/prod` | 28 s | **9.5 s** | 5 | 16 | - `File()` is served from the revision tarball, materialized by **one** `GET /archive/{rev}.tar.gz`; the raw endpoint is a bounded fallback only (archive disabled, gitlink). `TestForgejoSignalsFileCostIsConstantInTheFileCount` pins it: reading 120 files costs the same as reading 2. - Runs reads are two **filtered, bounded** windows — `?head_sha=<rev>` and `?head_branch=<gate>&event=push&page=1&limit=<n>` — because the endpoint ignores `limit` without a filter and otherwise returns the whole history (612 runs / ~10 MB / ~20 s on `infra-core`). Both cached; `RunsOnBranch` reaches `probeContext.runs()` through the new optional `BranchRunSource` seam and the windows are merged by identity. - `ForgejoSignals.MaxRequests` (default 16) is a hard stop that fails LOUDLY with `ForgejoRequestBudgetError`, so a re-introduced fan-out cannot silently spend the routine's window. The adapter refuses an unfiltered runs read outright. - `cmd/readiness` prints wall time and GET count per target, so cost is observed by the run rather than by a reviewer. Eight targets on this build is roughly two minutes of R-24's `maxDurationSeconds: 900` (>7× margin). ## Deviations from the brief (all deliberate, all visible) 1. **Gate branch is derived, not assumed.** The brief assumed default branch == gate branch. `Homelab/infra-core` and `Homelab/prod` run every gate on `live` and receive **zero** CI runs on `main`; scoring `main` would report "no run" for repos whose gate is green on every landing. Resolution order: definition override → branch most workflows trigger on (derived from primary sources) → default branch. Both three-tier repos name `live` explicitly in the definition as well. The digest prints the branch and its source, and the divergence from the default branch is a finding. 2. **`test_inventory` is per-class, not blended.** The brief's formula (`ran_by_ci / a` with packages over files) is unit-inconsistent and, applied to the real data, passes the very revision it was written to catch (`go test ./...` really does run 90% of api-sendrast's files). The rule implemented: a file is executed iff a gate step references its package, its `-tags` cover the file's build tags, and any `-run` filter matches a test function parsed out of the file; files are grouped by build-tag class and **every** class must be ≥ `test_class_min_ratio`. This is the brief's own `-run` mechanism, made to actually fire. 3. **`lint` does not read job detail.** Forgejo v14.0.3 has no `/actions/runs/{id}/jobs` endpoint (verified live: 404). The line uses the workflow file's own lint vocabulary plus that workflow's run status; the narrowing is stated in the definition's `detail`. The newest gate-branch run is read from the bounded push window (blocker-2 fix), not from the repo's whole history. 4. **The corpus parity test moved by three lines.** Adding a registered non-corpus routine to `registry.yaml` makes the reverse check ("registered but not in the corpus table") fire. It now derives the hosted 4.x set from `testdata/registry-4x-shapes.yaml` instead of listing it, so R-24 cannot claim an exemption the fixture does not grant. `testdata/corpus-table.md` is untouched (R-01…R-22 stays closed at 22); `TestRealRegistryLoads` expects 23. 5. **R-24's `targets.paths` gained one entry** (`Sendrast/sendrast-web`, the clean calibration target) on the orchestrator's calibration ruling. The definition's `targets:` list and the registry's authority are now asserted equal in `TestRealDefinitionLoads`, so they cannot drift. ## Pin discipline `routines -check` prints **23 routines, 4 active (R-03, R-06, R-19, R-24)**; `TestInProcessPinsMatchTheCode` is green on the new `sha256` for `readiness.go`. **Known limitation, stated rather than hidden:** the mechanism is a file *set* (`readiness_probes.go`, `readiness_workflows.go`, `readiness_{signals,git,forgejo,digest}.go` + the data file `readiness.yaml`); the LD4.4 pin test covers one file. Editing `readiness.go` after registration requires re-pinning R-24 — that is the routine's own anti-drift rule, and extending the pin to the whole set is queued as a follow-up rather than smuggled into this ticket. ## Shared files (minimal, as declared) - `routines/registry.yaml` — **my R-24 entry only** (siblings own R-25 and any 4.5a entry): the reserved-ids header comment, the "active today" count, and the R-24 `targets.paths` addition above. - `routines/ledger.go` — additive `Run.Target`, `ValidateFor`/`TargetRequired`, `RunFilter.Target`. No v2 stamp, no transport change. - `routines/registry_test.go`, `routines/parity_test.go`, `cmd/routines/main_test.go` — count/parity/census adjustments (the last derives the census and active set from `Registry.Census()` instead of hard-coding 22/3). - No `config/` keys needed; no dispatcher/spawn changes (enforcement is HOMELAB-1857). ## Window policy `emitsWork: false` and `RepairRefs(..., emit=false)` — **report-only**, per the ruling. Window two flips `emitsWork: true` with `emits: [R-07]` so the `readiness-repair:` tickets are visible to the entropy sweep; the dedup convention (`blocked_by` on the epic's first builder ticket) is documented as a human/agent act today, never as enforcement. ## Tests `go test -race ./...` and `go vet ./...` green in `lab-director/dispatcher`. No test opens a real socket. `routines/readiness_forgejo_test.go` drives the live adapter against an `httptest` fixture and asserts the request **shape** (one archive request for N files, zero raw reads, filtered/bounded runs windows, the budget stop, error/redaction paths); `routines/readiness_git_test.go` drives the offline seam against a real temp git checkout (revision pinning, `RunsFromFile` decoding, the branch-window merge) plus the `httptest`-free fixture paths.

aaron added 4 commits 2026-10-02 04:06:03 +00:00

HOMELAB-1730: chore(readiness): wip scoring definition (data, versioned) ... ecc9b023de

The heart of LD4.8: the seven scoring lines, the per-line/weakest-line floor
(never_below [ci_present, test_inventory], min_lines_passed 5 of 6 counted
lines, dev_env advisory v1), every threshold, the per-target override schema
(branch + advisory + neverBelow + a required reason), and the ruled target
scope. Data, not Go constants, so the floor changes in a reviewable diff.

Next: the definition loader (strict decode, unknown probe = refusal), the
mechanical probes, the scorer + report, the Forgejo/local-git signal adapters,
the R-24 registry entry, and the two-repo calibration.

HOMELAB-1730: feat(routines): readiness definition loader, seven probes, scorer, ledger target field ... 3de773a800

T1: ledger.Run gains an additive optional `target` field (ld.routine.run/v1
stays), ValidateFor/TargetRequired enforce it for a routine that declares
targets, RunFilter gains Target so the per-target read is one call.

T2/T3: readiness_definition.go loads readiness.yaml strictly (unknown key,
unknown probe, unreasoned override, floor contradictions, credential value =>
refusal with a line number); readiness_probes.go implements the seven probes
with the SEND-437 mechanism in test_inventory (package attribution + build tags
+ -run matched against the file's own test function names, per class ratio);
readiness.go scores weakest-line and renders the canonical JSON + markdown;
readiness_workflows.go parses workflow triggers/steps and derives the gate
branch from the workflows' own on: blocks (the fleet's three-tier repos gate on
`live`, not on the default branch).

HOMELAB-1730: feat(routines): forgejo+worktree signal adapters, cmd/readiness, digest, probe tests ... 4850eea22d

- readiness_git.go: WorktreeSignals (offline, rev-pinned via git) + RunsFromFile
  (a saved /actions/runs dump, so a calibration verdict is re-derivable).
- readiness_forgejo.go: read-only REST adapter (repo, tree, raw file, runs), one
  retry on 5xx/429, status-not-conclusion, token supplied by wiring and never
  logged.
- readiness_digest.go: the architect digest (below-floor first, narrowed floors
  printed) plus the window-two repair-ticket refs, off by default per the
  REPORT-ONLY ruling.
- cmd/readiness: the runnable mechanism (definition, targets, checkout or API,
  report dir, digest), exit 1 when a target is below floor.
- probe tests (fixtures only, no sockets): the SEND-437 shape reproduces as
  integration 2/42 (5%) with the untagged suite at 100%; build tags are honored;
  a -run slice cannot claim a file whose tests it does not select; the gate
  branch derives from the workflows' on: blocks; weakest-line floor; determinism.

HOMELAB-1730: feat(routines): register R-24 + calibration evidence ... 3b592e9bff

- registry.yaml: R-24 agent-readiness-score becomes real (active, weekly, seven
  owner/name targets, outputContract metricRow+artifact, emitsWork false per the
  REPORT-ONLY first-window ruling, pinned to readiness.go). Reserved-ids comment
  updated (R-23, R-25..R-27 remain reserved); corpus-table.md untouched.
- registry_test.go: 23 routines (22 corpus + R-24). parity_test.go: the
  "registered but not in the corpus" check now derives the hosted 4.x set from
  testdata/registry-4x-shapes.yaml instead of listing it, so R-24 cannot claim an
  exemption the fixture does not grant.
- ci_green now names the newest gate-branch run when the scored revision has no
  run of its own (evidence + finding), so "no run" is actionable.
- testdata/readiness-calibration.md + the four reports and three runs dumps:
  the SEND-437-class state reproduces exactly (ci_green pass, test_inventory fail
  at integration 9/74 = 12%), and the brief's expected "clean" verdict for
  Homelab/infra-core does NOT reproduce - documented with the three
  independently checkable reasons and the merge-commit-ungated finding.

aaron added 1 commit 2026-10-02 04:12:29 +00:00

HOMELAB-1730: test(routines): cmd/routines census and watchdog expectations follow the registry ... f18f3b839a

Registering R-24 makes the census 23 routines / 4 active, and the watchdog's
zero-row case now has four active routines. Both assertions are DERIVED from the
registry (Census().ActiveIDs) instead of hard-coded, so the next routine to earn
its mechanism does not fail these tests for the wrong reason.

go test -race ./... and go vet ./... green in lab-director/dispatcher.

aaron added 2 commits 2026-10-02 07:17:19 +00:00

HOMELAB-1730: fix(readiness): batch the revision from one archive request + hard request budget ... 0433c8d729

Landing review blocker 2 (undeclared API fan-out): the adapter read one
GET /raw/{path} per test file, so cost was linear in the repo's test
count (207 files ~= 5 min against R-24's 900 s window).

- File() is now served from the revision tarball, materialized by ONE
  /archive/{rev}.tar.gz request; the raw endpoint survives only as a
  bounded fallback (archive disabled, gitlink).
- Runs are two bounded, filtered windows (the endpoint ignores limit
  without a filter): head_sha=<rev> and head_branch=<gate>&event=push.
  Both cached.
- MaxRequests hard stop with a loud ForgejoRequestBudgetError.
- BranchRunSource + probeContext.runs() merge the gate-branch window.
- cmd/readiness reports per-target wall time + GET count on stderr.

HOMELAB-1730: test(readiness): httptest coverage for the live adapter + the offline seam ... b88313bb74

Landing review blocker 1: the PR body claimed httptest adapter tests for
the live Forgejo adapter and no test in the tree referenced ForgejoSignals
or WorktreeSignals. The claim is now true, and the tests assert the request
SHAPE the perf fix depends on:

- readiness_forgejo_test.go: scripted Forgejo fixture, tree+archive reads
  (one archive request for N files, zero raw reads), cost-constant-in-file-
  count, archive->raw fallback, filtered/bounded runs windows + caching,
  refusal of an unfiltered runs read, error paths (typed 404, 5xx retried
  once, decode, no base URL), credential redaction of error bodies, the
  request budget stop, RevFor, target, untar prefix strip + oversize refusal.
- readiness_git_test.go: real temp git checkout (revision pinning, tree,
  file, bad rev), Runs() requires a source, RunsFromFile dump decoding,
  BranchRunSource merge/dedupe + degraded-window finding.

aaron added 1 commit 2026-10-02 07:25:39 +00:00

HOMELAB-1730: fix(readiness): name a real clean calibration target + record the cost fix ... bf292983bc

The ticket's Verify line 1 needs a floor-passing repo to contrast the
SEND-437 scar against; the landing review found none in the ruled scope.

- Sendrast/sendrast-web @ aa500803 scores ready (6/6): ci.yml gates main,
  the scored sha has a green push run, the gate runs all 151 test files,
  4 docs files + a 238-line README, AGENTS.md at the root. Added to
  readiness.yaml targets and R-24 targets.paths (scored every window as
  the healthy control); the definition test now also asserts the
  definition's list cannot drift from the registry's authority.
- The ruling's named repo does not exist: Homelab/lab-director-contract
  404s, and ~/repos/lab-director-contract is a clone of aaron/lab-director,
  which scores 1/6 at both f2e16ae and current main (no gate, no README,
  no tests). Recorded with evidence; not forced, not added to the scope.
- readiness-calibration.md gains the clean target (§3), the 404 finding
  (§4), and the fan-out fix's before/after cost table (§6).

aaron commented 2026-10-02 07:26:31 +00:00

Author

Owner

Copy link

Fix worker — both blockers closed + calibration ruling applied

Commits on plane/HOMELAB-1730-readiness: 0433c8d (fan-out + budget), b88313b (adapter tests), bf29298 (clean calibration target + cost evidence). PR body corrected to state only what the diff proves. go test -race ./... + go vet ./... green in lab-director/dispatcher.

Blocker 1 — phantom adapter tests → CLAIM NOW TRUE (or removed where infeasible)

There were no adapter tests; now there are, and they assert the request shape, not just decoded output:

• routines/readiness_forgejo_test.go — scripted httptest Forgejo fixture: one archive request for N files / zero raw reads, cost-constant-in-file-count (TestForgejoSignalsFileCostIsConstantInTheFileCount: 120 files cost the same as 2), archive→raw bounded fallback, filtered+bounded runs windows with caching, refusal of an unfiltered runs read, typed 404 / 5xx-retried-once / decode / no-base-URL error paths, credential redaction of error bodies ([redacted], token never leaks), the request-budget stop, RevFor, target, tar prefix strip + oversize refusal.
• routines/readiness_git_test.go — real temp git checkout: revision pinning (tree/file at -rev), bad-rev failure, Runs() requires a source (unevaluated, never a pass), RunsFromFile dump decoding, BranchRunSource merge/de-dupe + degraded-window-as-finding.
• PR-body corrections: the httptest claim is now accurate; the false "no cmd/routines changes" line was removed (cmd/routines/main_test.go is in the diff — it is listed in Shared files).

Blocker 2 — undeclared API fan-out → batched, bounded, budgeted

File() is served from the revision tarball, materialized by one GET /archive/{rev}.tar.gz; raw is a bounded fallback only. Runs are two filtered windows (?head_sha=<rev>, ?head_branch=<gate>&event=push&page=1&limit=<n> — the endpoint ignores limit without a filter and otherwise returns the whole history: 612 runs / ~10 MB / ~20 s on infra-core). Both cached. MaxRequests (default 16) fails loudly with ForgejoRequestBudgetError. cmd/readiness now prints per-target wall time + GET count.

repo	before (review)	after	GETs (budget 16)
Homelab/infra-core	2 m 03 s	11.9 s	7
Sendrast/api-sendrast	~5 m	19.0 s	6
Homelab/prod	28 s	9.5 s	5

(GETs: branch resolve, 3 tree pages, archive, revision runs window, gate-branch window.) Eight targets ≈ 2 min of the 900 s window — >7× margin, and a re-introduced per-file read hits the budget instead of the window.

Calibration ruling — the named repo does not exist; a real clean target does

• Homelab/lab-director-contract → HTTP 404 on the instance (absent from the token's repo list). The checkout named ~/repos/lab-director-contract is a clone of aaron/lab-director, which scores 1/6 below-floor at both f2e16ae (contract-only state) and current main — no gate, no README, no tests, and ci_present is never_below, so no contract-only repo can pass by construction. Not forced, not added to the scope.
• CLEAN target found and added: Sendrast/sendrast-web @ aa500803 → ready (6/6) — ci.yml gates main, green push run for the scored sha, 151/151 (100%) test files executed, 4 docs files + 238-line README, lint gate green, AGENTS.md at root. Added to routines/readiness.yaml and R-24 targets.paths (scored every window as the healthy control); TestRealDefinitionLoads now also asserts the definition's target list cannot drift from the registry's authority. Report + trimmed runs dump committed.
• Second data point: Homelab/pi-extensions @ 93a0b5bbba67 → ready-with-concerns (5/6, only agent_context), measured read-only.
• routines/testdata/readiness-calibration.md + PR body updated (§3 clean target, §4 the 404, §6 cost).

Not merging — landing decision stays with the pipeline. Re-review me on head bf29298.

## Fix worker — both blockers closed + calibration ruling applied Commits on `plane/HOMELAB-1730-readiness`: `0433c8d` (fan-out + budget), `b88313b` (adapter tests), `bf29298` (clean calibration target + cost evidence). PR body corrected to state only what the diff proves. `go test -race ./...` + `go vet ./...` green in `lab-director/dispatcher`. ### Blocker 1 — phantom adapter tests → CLAIM NOW TRUE (or removed where infeasible) There were no adapter tests; now there are, and they assert the request **shape**, not just decoded output: - `routines/readiness_forgejo_test.go` — scripted `httptest` Forgejo fixture: one archive request for N files / zero raw reads, cost-constant-in-file-count (`TestForgejoSignalsFileCostIsConstantInTheFileCount`: 120 files cost the same as 2), archive→raw bounded fallback, filtered+bounded runs windows with caching, refusal of an unfiltered runs read, typed 404 / 5xx-retried-once / decode / no-base-URL error paths, credential redaction of error bodies (`[redacted]`, token never leaks), the request-budget stop, `RevFor`, target, tar prefix strip + oversize refusal. - `routines/readiness_git_test.go` — real temp git checkout: revision pinning (tree/file at `-rev`), bad-rev failure, `Runs()` requires a source (unevaluated, never a pass), `RunsFromFile` dump decoding, `BranchRunSource` merge/de-dupe + degraded-window-as-finding. - PR-body corrections: the `httptest` claim is now accurate; the false **"no `cmd/routines` changes"** line was removed (`cmd/routines/main_test.go` is in the diff — it is listed in Shared files). ### Blocker 2 — undeclared API fan-out → batched, bounded, budgeted `File()` is served from the revision tarball, materialized by **one** `GET /archive/{rev}.tar.gz`; raw is a bounded fallback only. Runs are two **filtered** windows (`?head_sha=<rev>`, `?head_branch=<gate>&event=push&page=1&limit=<n>` — the endpoint ignores `limit` without a filter and otherwise returns the whole history: 612 runs / ~10 MB / ~20 s on infra-core). Both cached. `MaxRequests` (default 16) fails loudly with `ForgejoRequestBudgetError`. `cmd/readiness` now prints per-target wall time + GET count. | repo | before (review) | after | GETs (budget 16) | |---|---|---|---| | `Homelab/infra-core` | 2 m 03 s | **11.9 s** | 7 | | `Sendrast/api-sendrast` | ~5 m | **19.0 s** | 6 | | `Homelab/prod` | 28 s | **9.5 s** | 5 | (GETs: branch resolve, 3 tree pages, archive, revision runs window, gate-branch window.) Eight targets ≈ 2 min of the 900 s window — >7× margin, and a re-introduced per-file read hits the budget instead of the window. ### Calibration ruling — the named repo does not exist; a real clean target does - **`Homelab/lab-director-contract` → HTTP 404** on the instance (absent from the token's repo list). The checkout named `~/repos/lab-director-contract` is a clone of **`aaron/lab-director`**, which scores **1/6 below-floor** at both `f2e16ae` (contract-only state) and current `main` — no gate, no README, no tests, and `ci_present` is `never_below`, so no contract-only repo can pass by construction. Not forced, not added to the scope. - **CLEAN target found and added: `Sendrast/sendrast-web @ aa500803` → `ready` (6/6)** — ci.yml gates `main`, green push run for the scored sha, `151/151 (100%)` test files executed, 4 docs files + 238-line README, lint gate green, `AGENTS.md` at root. Added to `routines/readiness.yaml` and R-24 `targets.paths` (scored every window as the healthy control); `TestRealDefinitionLoads` now also asserts the definition's target list cannot drift from the registry's authority. Report + trimmed runs dump committed. - Second data point: `Homelab/pi-extensions @ 93a0b5bbba67` → `ready-with-concerns` (5/6, only `agent_context`), measured read-only. - `routines/testdata/readiness-calibration.md` + PR body updated (§3 clean target, §4 the 404, §6 cost). **Not merging** — landing decision stays with the pipeline. Re-review me on head `bf29298`.

aaron added 1 commit 2026-10-02 07:30:13 +00:00

HOMELAB-1730: style(readiness): gofmt cmd/readiness after the cost-telemetry edit 071fac2814

aaron commented 2026-10-02 07:30:19 +00:00

Author

Owner

Copy link

Head is now 071fac2 (adds gofmt on cmd/readiness after the cost-telemetry edit; no behaviour change — gofmt -l clean, build + vet green). Everything in the previous fix-worker comment stands unchanged; re-review me on 071fac2.

Head is now `071fac2` (adds `gofmt` on `cmd/readiness` after the cost-telemetry edit; no behaviour change — `gofmt -l` clean, build + vet green). Everything in the previous fix-worker comment stands unchanged; re-review me on `071fac2`.

aaron force-pushed plane/HOMELAB-1730-readiness from 071fac2814 to 8597d0e945 2026-10-02 07:33:56 +00:00 Compare

aaron commented 2026-10-02 07:38:59 +00:00

Author

Owner

Copy link

Rebased onto epic/LD4 — PR is now mergeable

CI run #1725 on head 8597d0e is green (all four jobs). mergeable: true (was false: the branch was 13 commits behind epic/LD4).

• Rebase brought in R-25 (HOMELAB-1729, plan-freshness) and the LD4.5a alert-audit work.
• Conflicts were exactly the registry/census hunks, resolved to the merged totals: 22 corpus routines + R-24 (active, HOMELAB-1730) + R-25 (paused dep:routine-executor, HOMELAB-1729) = 24 registered, 4 active.
  • registry_test.go: kept epic/LD4's derived floor plus R-25's shape assertions, raised the floor to 24 (was != 23).
  • parity_test.go: merged both intents — ids < R-23 must be in the corpus table; ids ≥ R-23 must be in the derived hosted-4.x fixture (from testdata/registry-4x-shapes.yaml) or name their owning ticket; hostedIDs helper retained.
  • cmd/routines/main_test.go: kept the census count derived from Registry.Census() (no hard-coded total) and asserted R-24 + R-25 are present.
  • registry.yaml header reconciled: R-23, R-26, R-27 remain reserved.
• The three fix-worker deliverables are unchanged and re-verified on the rebased tree: go test -race ./... + go vet ./... green across all 23 packages (incl. planfresh), calibration reports still byte-identical offline, and the clean target (Sendrast/sendrast-web @ aa500803 → ready 6/6) still in R-24's targets.paths.

Not merging — re-review me on 8597d0e.

## Rebased onto `epic/LD4` — PR is now mergeable CI run #1725 on head **`8597d0e`** is green (all four jobs). `mergeable: true` (was `false`: the branch was 13 commits behind `epic/LD4`). - Rebase brought in R-25 (HOMELAB-1729, plan-freshness) and the LD4.5a alert-audit work. - Conflicts were exactly the registry/census hunks, resolved to the merged totals: 22 corpus routines + **R-24** (active, HOMELAB-1730) + **R-25** (paused `dep:routine-executor`, HOMELAB-1729) = **24 registered, 4 active**. - `registry_test.go`: kept `epic/LD4`'s derived floor plus R-25's shape assertions, raised the floor to 24 (was `!= 23`). - `parity_test.go`: merged both intents — ids < R-23 must be in the corpus table; ids ≥ R-23 must be in the derived hosted-4.x fixture (from `testdata/registry-4x-shapes.yaml`) **or** name their owning ticket; `hostedIDs` helper retained. - `cmd/routines/main_test.go`: kept the census count derived from `Registry.Census()` (no hard-coded total) and asserted `R-24` + `R-25` are present. - `registry.yaml` header reconciled: R-23, R-26, R-27 remain reserved. - The three fix-worker deliverables are unchanged and re-verified on the rebased tree: `go test -race ./...` + `go vet ./...` green across all 23 packages (incl. `planfresh`), calibration reports still byte-identical offline, and the clean target (`Sendrast/sendrast-web @ aa500803` → `ready` 6/6) still in R-24's `targets.paths`. Not merging — re-review me on `8597d0e`.

aaron commented 2026-10-02 08:04:48 +00:00

Author

Owner

Copy link

Landing review (delta re-review) — verdict: CLEAN, both blockers CLOSED

Posted by the orchestrator on behalf of the delta landing worker, whose own comment attempt fell victim to the aaron/-slug silent-drop documented earlier on #577. Review basis: the worker's full delta review of head 8597d0e (CI run #1725 green), completed 2026-10-02.

• Blocker 1 (phantom adapter-test claims): CLOSED. routines/readiness_forgejo_test.go (640 lines) and routines/readiness_git_test.go (274) are real: one archive GET for N files, cost-constant-in-file-count, budget stop, redaction, error paths; PR body claims corrected to match the diff.
• Blocker 2 (undeclared API fan-out): CLOSED, re-measured live by the reviewer — Homelab/infra-core 6.8 s / 7 GETs, Sendrast/api-sendrast 20.1 s / 6 GETs (fix-worker claimed 11.9/7 and 19.0/6; GET counts exact, wall times same order) — ≤2% of the 900 s routine budget.
• routines -check = 24 routines, 4 active on the rebased tree; registry/parity/main-test conflicts resolved to merged totals.
• Clean calibration target Sendrast/sendrast-web @ aa500803 → ready 6/6 verified; the ruled repo (lab-director-contract) 404 documented with evidence, not forced.

No open blocker findings. Landing lock: CI green on head 8597d0e, this verdict posted after head, no blockers.

## Landing review (delta re-review) — verdict: CLEAN, both blockers CLOSED Posted by the orchestrator on behalf of the delta landing worker, whose own comment attempt fell victim to the aaron/-slug silent-drop documented earlier on #577. Review basis: the worker's full delta review of head `8597d0e` (CI run #1725 green), completed 2026-10-02. - **Blocker 1 (phantom adapter-test claims): CLOSED.** `routines/readiness_forgejo_test.go` (640 lines) and `routines/readiness_git_test.go` (274) are real: one archive GET for N files, cost-constant-in-file-count, budget stop, redaction, error paths; PR body claims corrected to match the diff. - **Blocker 2 (undeclared API fan-out): CLOSED, re-measured live by the reviewer** — `Homelab/infra-core` **6.8 s / 7 GETs**, `Sendrast/api-sendrast` **20.1 s / 6 GETs** (fix-worker claimed 11.9/7 and 19.0/6; GET counts exact, wall times same order) — ≤2% of the 900 s routine budget. - `routines -check` = **24 routines, 4 active** on the rebased tree; registry/parity/main-test conflicts resolved to merged totals. - Clean calibration target `Sendrast/sendrast-web @ aa500803` → ready 6/6 verified; the ruled repo (lab-director-contract) 404 documented with evidence, not forced. No open blocker findings. Landing lock: CI green on head `8597d0e`, this verdict posted after head, no blockers.

aaron merged commit 4672e8ee05 into epic/LD4 2026-10-03 03:03:29 +00:00

aaron referenced this pull request from a commit 2026-10-03 03:03:30 +00:00

Merge pull request 'HOMELAB-1730: feat(routines): LD4.8 agent-readiness score (R-24)' (#576) from plane/HOMELAB-1730-readiness into epic/LD4

aaron referenced this pull request 2026-10-03 03:13:14 +00:00

LD4 (HOMELAB-1713): The Loops — intake, El Director, routines, readiness, plan-freshness, meetings, alert audit → live #591

aaron referenced this pull request 2026-10-03 18:17:54 +00:00

LD4 (HOMELAB-1713): The Loops — intake, El Director, routines, readiness, plan-freshness, meetings, alert audit → live #591

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

operator-review

Requires human operator review before merge — dangerous class (RBAC, secrets, network policy, Terraform) or explicitly gated. Never auto-merge.

No labels

operator-review

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

Homelab/infra-core!576

No description provided.