aaron/lab-director
1
0
Fork 0
Code Issues Pull requests 5 Projects Releases Packages Wiki Activity Actions

HOMELAB-2174: docs(contract): Amendment 5, no duplicate authorities + authority map #11

Open
aaron wants to merge 0 commits from plane/HOMELAB-2174-amendment-5 into main
pull from: plane/HOMELAB-2174-amendment-5
merge into: aaron:main
Conversation 1 Commits - Files changed -
aaron commented 2026-10-22 05:32:06 +00:00
Owner
Copy link

What

Contract Amendment 5 (operator ruling 2026-10-21, HOMELAB-1968 "as recommended" — the
narrow option). Only the operator amends this contract: this PR is opened for the
operator to review and merge. The worker does not merge it.

spec/contract.md v0.9.1 → v0.9.2:

  • §11: no new databases (state in Plane, memory in role-lore PVCs, ledger in JetStream, docs in Outline/exhibits) → no duplicate authorities — no new database may hold a second writable copy of a fact another store owns, followed by the four-row authority map:

    Fact Authority (the only writable owner)
    Ticket state and signs Plane
    Workflow, node and event records; sign snapshots The LD record DB (the lab-director Postgres)
    Code, config and memory Git
    Docs Outline

    plus one paragraph: anything the DB holds of another store's fact is a rebuildable projection (source identity + revision, reconstructable from the owning store alone); a new store or table names its row in the map before it is built.

  • Frontmatter: version bumped; status line records Amendment 5 (five amendments recorded, this PR's merge is the approval).

  • Amendments log: item 5 appended in the file's existing (operator, YYYY-MM-DD) **Title** format, including the corpus waiver (below) and the Amendment 6 deferral.

  • AGENTS.md twin: re-synced byte-for-byte (diff clean). The repo-root AGENTS.md is the same document; version discipline requires one state.

Deliberately not changed: the rest of §11 (JetStream ledger, role-lore PVCs memory, the standing-credentials wording) — stale by the approved design, deferred to Amendment 6 (HOMELAB-2175) so this ruling stays small, per the operator's ruling.

Dispatcher corpus — waived, not forgotten

prod/manifests/lab-director/dispatcher-corpus.yaml:337-345 still compiles v0.9.1 §11 into the agent context. It is not touched by this PR: HOMELAB-1925 (LD-N0.5) is Done — dispatcher-deployment.yaml has replicas: 0 on origin/live, arms.custodian/arms.signals are false, and no dispatcher pod reads the corpus. The corpus is re-cut at re-arm (LD5-B11). The waiver is recorded in the amendment text itself; a waiver comment is also posted on HOMELAB-2174.

Known follow-ups (not blockers)

  • infra-core code comments citing §11: lab-director/dispatcher/README.md:512, dispatcher/direction/source.go:20, dispatcher/signalintake/signal.go:53 — the citation stays true in spirit ("Plane is the store"), the text they quote is now v0.9.2; fold into the B11 re-arm.
  • prod/manifests/lab-director/README.md §"Audit — the ledger already exists, twice" also quotes the old clause — same re-arm sweep.
  • Amendment 6 (HOMELAB-2175) drafts the remaining stale §11 store clauses.

Verify

  • §11 reads "no duplicate authorities" with the 4-row authority map; version bumped; Amendment 5 appended
  • AGENTS.md twin in sync (diff spec/contract.md AGENTS.md → empty)
  • Operator approval recorded on this PR (the operator's merge is the approval)
  • Dispatcher corpus refresh explicitly waived — HOMELAB-1925 Done, dispatcher at 0 replicas in prod
  • Landed before HOMELAB-1933's schema review (B5)
  • go build ./... + go test ./... pass on the head commit (only Markdown changed; the golden internal/harness/claudecode/testdata contract is a separate fixture and is untouched)

Decision: HOMELAB-1968 · Ticket: HOMELAB-2174 · Trail: HOMELAB-1654

## What Contract Amendment 5 (operator ruling 2026-10-21, HOMELAB-1968 "as recommended" — the narrow option). **Only the operator amends this contract: this PR is opened for the operator to review and merge. The worker does not merge it.** `spec/contract.md` v0.9.1 → **v0.9.2**: - **§11**: `no new databases (state in Plane, memory in role-lore PVCs, ledger in JetStream, docs in Outline/exhibits)` → **`no duplicate authorities — no new database may hold a second writable copy of a fact another store owns`**, followed by the four-row authority map: | Fact | Authority (the only writable owner) | |---|---| | Ticket state and signs | **Plane** | | Workflow, node and event records; sign snapshots | **The LD record DB** (the lab-director Postgres) | | Code, config and memory | **Git** | | Docs | **Outline** | plus one paragraph: anything the DB holds of another store's fact is a **rebuildable projection** (source identity + revision, reconstructable from the owning store alone); a new store or table names its row in the map before it is built. - **Frontmatter**: version bumped; status line records Amendment 5 (five amendments recorded, this PR's merge is the approval). - **Amendments log**: item 5 appended in the file's existing `(operator, YYYY-MM-DD) **Title**` format, including the corpus waiver (below) and the Amendment 6 deferral. - **`AGENTS.md` twin**: re-synced byte-for-byte (`diff` clean). The repo-root `AGENTS.md` is the same document; version discipline requires one state. Deliberately **not** changed: the rest of §11 (JetStream ledger, role-lore PVCs memory, the standing-credentials wording) — stale by the approved design, deferred to Amendment 6 (HOMELAB-2175) so this ruling stays small, per the operator's ruling. ## Dispatcher corpus — waived, not forgotten `prod/manifests/lab-director/dispatcher-corpus.yaml:337-345` still compiles v0.9.1 §11 into the agent context. **It is not touched by this PR**: HOMELAB-1925 (LD-N0.5) is Done — `dispatcher-deployment.yaml` has `replicas: 0` on `origin/live`, `arms.custodian`/`arms.signals` are `false`, and no dispatcher pod reads the corpus. The corpus is re-cut at re-arm (LD5-B11). The waiver is recorded in the amendment text itself; a waiver comment is also posted on HOMELAB-2174. ## Known follow-ups (not blockers) - `infra-core` code comments citing §11: `lab-director/dispatcher/README.md:512`, `dispatcher/direction/source.go:20`, `dispatcher/signalintake/signal.go:53` — the citation stays true in spirit ("Plane is the store"), the text they quote is now v0.9.2; fold into the B11 re-arm. - `prod/manifests/lab-director/README.md` §"Audit — the ledger already exists, twice" also quotes the old clause — same re-arm sweep. - Amendment 6 (HOMELAB-2175) drafts the remaining stale §11 store clauses. ## Verify - [x] §11 reads "no duplicate authorities" with the 4-row authority map; version bumped; Amendment 5 appended - [x] `AGENTS.md` twin in sync (`diff spec/contract.md AGENTS.md` → empty) - [ ] Operator approval recorded on this PR (the operator's merge **is** the approval) - [x] Dispatcher corpus refresh explicitly waived — HOMELAB-1925 Done, dispatcher at 0 replicas in prod - [ ] Landed before HOMELAB-1933's schema review (B5) - [x] `go build ./...` + `go test ./...` pass on the head commit (only Markdown changed; the golden `internal/harness/claudecode/testdata` contract is a separate fixture and is untouched) Decision: HOMELAB-1968 · Ticket: HOMELAB-2174 · Trail: HOMELAB-1654 
§11's "no new databases" is replaced by "no new database may hold a second
writable copy of a fact another store owns", with the four-row authority map
(Plane: ticket state and signs · the LD record DB: workflow/node/event records
and sign snapshots · Git: code, config and memory · Outline: docs). Copies the
DB holds of another store's fact are rebuildable projections.

Version 0.9.1 → 0.9.2, Amendment 5 appended to the amendments log per the
existing format, and the AGENTS.md twin re-synced byte-for-byte (it is the same
document). Operator ruling 2026-10-21 on HOMELAB-1968, narrow option; the stale
remainder of §11 is deferred to Amendment 6 (HOMELAB-2175).

The compiled dispatcher corpus is deliberately NOT refreshed here: the
dispatcher is parked at replicas: 0 in prod (HOMELAB-1925, Done) and the corpus
is re-cut at re-arm (LD5-B11). Waiver recorded in the amendment text.
aaron commented 2026-10-22 05:38:45 +00:00
Author
Owner
Copy link

Landing review — verdict: APPROVE (0 blockers, 2 non-blocking concerns)

Reviewer: fresh landing context (deepseek). Sources: PR diff at head 0c2b917, HOMELAB-2174 verify checklist, HOMELAB-1968 ruling, origin/main base, prod@origin/live, live cluster (read-only). The implementer's summary was not used as evidence.

Acceptance criteria (HOMELAB-2174) — checked against the files, not the PR body

Box Verdict Evidence
§11 reads "no duplicate authorities" + exact 4-row map PASS spec/contract.md:139-142 new clause; map at :149-156 — Plane = ticket state and signs; LD record DB = workflow, node and event records; sign snapshots; Git = code, config and memory; Outline = docs. Wording matches the ticket row-for-row. :158-162 adds the rebuildable-projection rule.
Version bumped PASS :3 version: 0.9.1 → 0.9.2 (Amendment 5: …); :4 status line carries five amendments. No other 0.9.1 survives outside design/ and synthetic testdata fixtures (gate-register.md:111 is herdr ≥0.9.1, unrelated).
Amendment 5 appended in the existing format PASS :200-213 5. (operator, 2026-10-21) **Title:** matches items 1–4 (:186-199) in shape and indentation.
AGENTS.md twin in sync PASS — verified independently Extracted both blobs at head: sha256 79977927…f20488 for spec/contract.md and AGENTS.md, 213 lines each; diff empty. The twin was already identical on origin/main (184/184), so the PR body's claim is accurate and the twin is not being used to smuggle extra content.
Dispatcher corpus refreshed or waived because the dispatcher is at 0 PASS — waiver claim checks out Corpus still quotes v0.9.1 §11 verbatim at prod@origin/live:manifests/lab-director/dispatcher-corpus.yaml:339. Parked: dispatcher-deployment.yaml:208 replicas: 0 under # PARKED AT replicas: 0 (HOMELAB-1925) (:76), arms.custodian: false (dispatcher-config.yaml:623), arms.signals: false (:663), all arms false (:584-663). Live cluster: deploy/lab-director-dispatcher in namespace agent-tools is 0/0, zero dispatcher pods. HOMELAB-1925 is Done.
Operator approval on the PR pending — correctly left open Only the operator amends the contract; this review does not merge.

Scope — clean

Exactly 2 files, both Markdown (git diff --stat origin/main...head: AGENTS.md, spec/contract.md, +76/−18). One commit. No design, code, manifest, or prod file touched; branch is a fast-forward of main. Testdata v0.9.1 fixtures are synthetic render fixtures (10-line excerpt, no §11 text) and no test compares them to the real spec.

Concerns (non-blocking — operator's call, not merge gates)

  1. spec/contract.md:206-207 (identical AGENTS.md:206-207) — the deferral sentence is inaccurate on 2 of its 3 items. It says the "remainder of §11 … (the JetStream ledger, role-lore PVCs as memory, the standing-credentials wording) is deferred to Amendment 6". Only the standing-credentials wording still exists (:143). "JetStream ledger" and "role-lore PVCs as memory" lived inside the parenthetical of the clause this PR replaces and are now gone from the file entirely — removed, not deferred. Since this is frozen authority text that Amendment 6 (HOMELAB-2175) will read, suggest: "…the remainder of §11 (the standing-credentials wording) is deferred to Amendment 6; the JetStream-ledger and role-lore-PVC wording left with the replaced clause."
  2. The waiver is correct but "inert" is the wrong reason to record. dispatcher-config.yaml:320-333 on origin/live has context.author: files with per-section sha256 pins over the corpus bytes — any unpark reads the corpus and gets v0.9.1 §11. So the corpus is inert only because the workload is at 0, not by wiring. Consequence for LD5-B11: a re-cut must move the corpus section, the README pin table, these pins: and checksum/corpus in dispatcher-deployment.yaml:237,287 in one commit (already documented at dispatcher-config.yaml:295-300). Also note prod/manifests/lab-director/README.md:59 still claims "Inert: mounted, never read — context.author: none", which is stale vs origin/live; worth sweeping at the same re-arm. None of this invalidates the waiver: the ticket's condition is "scaled to 0", and it is.

Risk / breadth vs the ruling (HOMELAB-1968 narrow)

Nothing broader than the ruling. The whole replaced clause is quoted in the diff, every other §11 clause is byte-preserved (:143-148), and the map's memory row (Git) is the ticket's own wording, not an invention. Only concern 1 above is an over-broad sentence (claiming a deferral for text that was removed), not an over-broad amendment.

No merge performed — the operator amends and merges the contract.

## Landing review — verdict: APPROVE (0 blockers, 2 non-blocking concerns) Reviewer: fresh landing context (deepseek). Sources: PR diff at head `0c2b917`, HOMELAB-2174 verify checklist, HOMELAB-1968 ruling, `origin/main` base, `prod@origin/live`, live cluster (read-only). The implementer's summary was not used as evidence. ### Acceptance criteria (HOMELAB-2174) — checked against the files, not the PR body | Box | Verdict | Evidence | |---|---|---| | §11 reads "no duplicate authorities" + exact 4-row map | PASS | `spec/contract.md:139-142` new clause; map at `:149-156` — Plane = ticket state and signs; LD record DB = workflow, node and event records; sign snapshots; Git = code, config and memory; Outline = docs. Wording matches the ticket row-for-row. `:158-162` adds the rebuildable-projection rule. | | Version bumped | PASS | `:3` `version: 0.9.1 → 0.9.2 (Amendment 5: …)`; `:4` status line carries five amendments. No other `0.9.1` survives outside `design/` and synthetic testdata fixtures (`gate-register.md:111` is herdr ≥0.9.1, unrelated). | | Amendment 5 appended in the existing format | PASS | `:200-213` `5. (operator, 2026-10-21) **Title:**` matches items 1–4 (`:186-199`) in shape and indentation. | | AGENTS.md twin in sync | PASS — verified independently | Extracted both blobs at head: `sha256 79977927…f20488` for `spec/contract.md` **and** `AGENTS.md`, 213 lines each; `diff` empty. The twin was already identical on `origin/main` (184/184), so the PR body's claim is accurate and the twin is not being used to smuggle extra content. | | Dispatcher corpus refreshed **or** waived because the dispatcher is at 0 | PASS — waiver claim checks out | Corpus still quotes v0.9.1 §11 verbatim at `prod@origin/live:manifests/lab-director/dispatcher-corpus.yaml:339`. Parked: `dispatcher-deployment.yaml:208` `replicas: 0` under `# PARKED AT replicas: 0 (HOMELAB-1925)` (`:76`), `arms.custodian: false` (`dispatcher-config.yaml:623`), `arms.signals: false` (`:663`), all arms false (`:584-663`). Live cluster: `deploy/lab-director-dispatcher` in namespace **agent-tools** is `0/0`, zero dispatcher pods. HOMELAB-1925 is `Done`. | | Operator approval on the PR | pending — correctly left open | Only the operator amends the contract; this review does not merge. | ### Scope — clean Exactly 2 files, both Markdown (`git diff --stat origin/main...head`: `AGENTS.md`, `spec/contract.md`, +76/−18). One commit. No design, code, manifest, or `prod` file touched; branch is a fast-forward of `main`. Testdata `v0.9.1` fixtures are synthetic render fixtures (10-line excerpt, no §11 text) and no test compares them to the real spec. ### Concerns (non-blocking — operator's call, not merge gates) 1. `spec/contract.md:206-207` (identical `AGENTS.md:206-207`) — the deferral sentence is inaccurate on 2 of its 3 items. It says the "remainder of §11 … (the JetStream ledger, role-lore PVCs as memory, the standing-credentials wording) is deferred to Amendment 6". Only the standing-credentials wording still exists (`:143`). "JetStream ledger" and "role-lore PVCs as memory" lived inside the parenthetical of the clause this PR replaces and are now gone from the file entirely — removed, not deferred. Since this is frozen authority text that Amendment 6 (HOMELAB-2175) will read, suggest: "…the remainder of §11 (the standing-credentials wording) is deferred to Amendment 6; the JetStream-ledger and role-lore-PVC wording left with the replaced clause." 2. The waiver is correct but "inert" is the wrong reason to record. `dispatcher-config.yaml:320-333` on `origin/live` has `context.author: files` with per-section sha256 pins over the corpus bytes — any unpark reads the corpus and gets v0.9.1 §11. So the corpus is inert *only because the workload is at 0*, not by wiring. Consequence for LD5-B11: a re-cut must move the corpus section, the README pin table, these `pins:` and `checksum`/`corpus` in `dispatcher-deployment.yaml:237,287` in one commit (already documented at `dispatcher-config.yaml:295-300`). Also note `prod/manifests/lab-director/README.md:59` still claims "**Inert**: mounted, never read — `context.author: none`", which is stale vs `origin/live`; worth sweeping at the same re-arm. None of this invalidates the waiver: the ticket's condition is "scaled to 0", and it is. ### Risk / breadth vs the ruling (HOMELAB-1968 narrow) Nothing broader than the ruling. The whole replaced clause is quoted in the diff, every other §11 clause is byte-preserved (`:143-148`), and the map's memory row (Git) is the ticket's own wording, not an invention. Only concern 1 above is an over-broad *sentence* (claiming a deferral for text that was removed), not an over-broad amendment. **No merge performed** — the operator amends and merges the contract.
This branch is already included in the target branch. There is nothing to merge.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin plane/HOMELAB-2174-amendment-5:plane/HOMELAB-2174-amendment-5
git switch plane/HOMELAB-2174-amendment-5

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main
git merge --no-ff plane/HOMELAB-2174-amendment-5
git switch plane/HOMELAB-2174-amendment-5
git rebase main
git switch main
git merge --ff-only plane/HOMELAB-2174-amendment-5
git switch plane/HOMELAB-2174-amendment-5
git rebase main
git switch main
git merge --no-ff plane/HOMELAB-2174-amendment-5
git switch main
git merge --squash plane/HOMELAB-2174-amendment-5
git switch main
git merge --ff-only plane/HOMELAB-2174-amendment-5
git switch main
git merge plane/HOMELAB-2174-amendment-5
git push origin main
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
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
aaron/lab-director!11
No description provided.