admin
b03a105375
gates / gates (push) Successful in 17s
Hub only. No controller change, no agent change, no wire change — nothing to bake. demo-hp untouched: the operator is re-deploying it this evening. R-323 — the five-word phrase is „Tulajdonosi jelmondat". It was „Visszaállító jelszó": one word from the name retired last week, and false besides — it restores nothing, it proves the account owns the box being bound. Five sites, all in the hub; felhom-controller and felhom-agent carry the name nowhere, so no halt and no bake. Both suggested names were rejected with reasons: „Fiókjelszó" would collide with the dashboard login (a DIFFERENT real secret), and „Összekötési jelszó" would leave the two factors on this page separated only by kód-versus-jelszó — the exact shape being removed, since the other factor is the „Párosító kód". The chosen name differs on both axes, stem and noun. Naming only; the acceptance pin drives the real handler. R-324 — the hub's customer copy is under a guard for the first time. Retired names banned across all 95 hub files; retrieval stems registered in four declared customer surfaces. The selftest found a defect in its own instrument on the first run. One shared vocabulary in scripts/, drift-checked into the controller gate rather than copied (R-325 removes the scaffold). R-321 — a machine we told to be quiet is no longer reported as dead, and it was two doors, not one: because the state is RECORDED rather than deleted, the morning deadline check can skip it too. A deleted state returns "", which is not "down" — R-195's shape returning through a second door. The clock runs from the report the hub can see, so re-enabling starts it there and emits no recovery for an outage that never happened. Three red-proofs; the one that matters showed a genuinely dead machine sitting at "disabled" when the suppression was made unconditional. R-326 — "which claims are unproven" is answerable by a command now. The nine I have been repeating was the count of claims the 9 August pass DOWNGRADED, not the count of unproven ones. The real figures: 55 claims, 23 walked, 32 not — and only 6 of those 32 cite evidence. Its first run found a stale claim (R-327).
140 lines
8.5 KiB
Markdown
140 lines
8.5 KiB
Markdown
# CLAUDE.md — `felhom.eu`
|
|
|
|
> Stable orientation only — **current state lives in `CONTEXT.md` and the tops of
|
|
> `hub/CHANGELOG.md` / `scripts/CHANGELOG.md` / `website/CHANGELOG.md`**, never here. Cross-repo
|
|
> conventions (the three-component model, artifact taxonomy, access, clean-tree gate, secrets):
|
|
> workspace-root `/mnt/5_hdd/felhom.eu/git/CLAUDE.md`, whose versioned copy is
|
|
> `documentation/runbooks/workspace-CLAUDE.md`. Path-scoped detail: `.claude/rules/`.
|
|
|
|
## What this repo is
|
|
|
|
Four surfaces in one repo, plus the design home for the whole system:
|
|
|
|
- `hub/` — **felhom-hub**, the operator backend (Go, k3s, `hub.felhom.eu`).
|
|
- `website/` — static HTML at felhom.eu, served by k3s nginx + git-sync.
|
|
- `manifests/` — k3s manifests for felhom-system, GitOps via one ArgoCD app.
|
|
- `scripts/` — the **public installer** (`felhom-host-install.sh`) and this repo's gates.
|
|
- `documentation/` — the **authoritative design home for all of Felhom**, not just this repo.
|
|
- `skills/` — versioned source of the Claude Code skills; install with
|
|
`python3 scripts/install_skills.py` (symlink — repo edits are live immediately).
|
|
|
|
## Doing X → read Y
|
|
|
|
| Doing | Read |
|
|
|---|---|
|
|
| writing any new code | `REUSE.md` — helpers, seams, extension points, traps |
|
|
| needing current state / roadmap | `CONTEXT.md` |
|
|
| hub work (architecture, deploy, patterns) | loads itself: `.claude/rules/hub.md` |
|
|
| website or installer work | loads itself: `.claude/rules/website.md` |
|
|
| manifests / ArgoCD / secrets | loads itself: `.claude/rules/manifests.md` |
|
|
| writing or routing a document | loads itself: `.claude/rules/docs.md` |
|
|
| build, deploy, publish, verify a version | the **`felhom-build-deploy`** skill |
|
|
| writing or reviewing a test, fixing a bug | the **`felhom-testing`** skill |
|
|
| UI, tokens, badges, Hungarian copy | the **`felhom-ui-design`** skill |
|
|
| host addresses, break-glass, node facts | `documentation/operations/nodes.md` — never restate them |
|
|
| which box may I break | `documentation/runbooks/target-selection.md` |
|
|
| what version is live anywhere | ask the hub (`/hosts`, `/configs`) or the box — **never a doc** |
|
|
| the authoritative design | `documentation/architecture/01..05-*.md` |
|
|
|
|
## Code quality
|
|
|
|
- If you need more input or troubleshooting output, **ask first — don't guess**.
|
|
- **A `go test -run` pattern that matches no test prints `ok` and exits 0.** A red-proof using `-run`
|
|
must first prove the filter matched something (`-v`, look for `=== RUN`). Generally: **an
|
|
instrument that can drop results silently is not a measurement.**
|
|
|
|
<!--
|
|
go test -run: found 2026-08-02 while red-proofing — `-run TestCustomerUnified` matched nothing in the
|
|
target file and reported `ok ... 0.062s`, which was read as a passing red-proof. This is the "an
|
|
absent line is not evidence" rule aimed at the one place a false green costs most: the proof itself.
|
|
The same class bit twice that day — a `| tail -5` inside a census query silently dropped rows and
|
|
looked exactly like a real finding.
|
|
-->
|
|
|
|
## The installer publishes by TAG, not by push (R-110)
|
|
|
|
This fence is in the core deliberately: its trigger is editing `scripts/felhom-host-install.sh`, and
|
|
no path-scoped rule covers that file. It governs the one artifact that runs **as root on a virgin
|
|
box**.
|
|
|
|
- **Pushing `scripts/felhom-host-install.sh` to `main` publishes NOTHING.** `manifests/webpage.yaml`
|
|
runs two git-syncs: the website from `main`, and `/scripts/` from the tag
|
|
`installer-v<SCRIPT_VERSION>`.
|
|
- **To publish:** cut `installer-v<new SCRIPT_VERSION>`, bump the `--ref` in `webpage.yaml` (**both**
|
|
the sidecar and the init container), commit, sync.
|
|
- **To roll back:** move the tag back and wait ~30 s. No ArgoCD sync, no deploy — that is the
|
|
emergency lever; fix forward afterwards.
|
|
- **Do NOT pin the website to the tag**, and the URL never carries a ref — `felhom-bootstrap.sh` and
|
|
the hub's day-0 command follow the tag with no edit.
|
|
- `hostinstall_gates.py` gate 6 fails if the manifest stops naming an `installer-v…` tag or if the
|
|
website stops tracking `main`.
|
|
|
|
## Workflow — what is specific to this repo
|
|
|
|
- **Never `git add -A` here** — parallel sessions share the clone and it sweeps foreign WIP. Stage
|
|
explicit paths only, `git pull --rebase` before every push.
|
|
- **`REPORT.md` is overwritten, so two sessions in this repo clobber each other.** The second session
|
|
writes **`REPORT-<topic>.md`** and never touches the shared `REPORT.md`.
|
|
- `CHANGELOG.md` here is **per-area**: `hub/`, `scripts/`, `website/`.
|
|
|
|
<!-- The sweep incident: v0.47.0, commit 146d165 — a red-proof-mutated guard got swept to main. -->
|
|
|
|
## Gates — ONE entry point
|
|
|
|
**Run `python3 scripts/repo_gates.py` after ANY change in this repo.** It runs every gate —
|
|
`site_gates.py`, `hostinstall_gates.py`, `hub_confirm_gate.py`, `manifest_bearer_gate.py`,
|
|
`reuse_refs_check.py` and `instructions_gate.py` — streaming each gate's own output and exiting
|
|
non-zero if any fails. `--fast` selects the gates that touch no network and no container runtime;
|
|
today that is all of them. **A missing gate script is a FAILURE, never a skip.**
|
|
|
|
`site_gates.py` is a *gate*, not a runner — do not model new work on it;
|
|
`app-catalog-felhom.eu/scripts/catalog_gates.py` is the canonical runner (R-161).
|
|
|
|
**The pre-push hook** (`.githooks/pre-push`) runs it with `--fast` and refuses a failing push. It is
|
|
**per-clone** — switch it on once with `git config core.hooksPath .githooks`, and a manual run WARNS
|
|
when this clone is unarmed. `git push --no-verify` bypasses it deliberately; **say so in the session
|
|
report when you use it** — CI re-runs the same entry point on every push and **emails the operator
|
|
on failure**, so a bypass is noticed even though it is not blocked (R-168, CLOSED 2026-08-02; CI
|
|
reports rather than refuses because there is no PR to gate — R-169).
|
|
|
|
<!--
|
|
WHY A RUNNER AND NOT FIVE INVOCATIONS (2026-08-02, R-29): a census of all thirteen gates across the
|
|
four repos found that every check a CLAUDE.md names was passing, and two of the four nobody is told
|
|
to run were failing — one since 14 July. The single-entry-point shape is the only one that
|
|
demonstrably gets run here.
|
|
|
|
instructions_gate joined the list on 2026-08-06 (R-229 deferred leg). It is registered in the
|
|
controller and agent runners too, and it is the SHARED copy in felhom.eu/scripts/ — never copied
|
|
into a sibling repo, because a copy would recreate the drift it detects.
|
|
-->
|
|
|
|
## End-of-session checklist
|
|
|
|
Registers first — **a finding goes in `documentation/backlog/OPEN-ITEMS.md` first**, never only in a
|
|
report, an audit or `STATUS.md`. Four items in this project were minted in a spike doc and lost
|
|
(R-153/154/155, R-156/157). This applies to **every** session that ships, breaks or decides
|
|
something, not only sessions that touch `documentation/` — which is why it is here and not in
|
|
`docs.md`.
|
|
|
|
- **`CHANGELOG.md` + `REPORT.md`** in every repo touched (see the workspace root for the rule, and
|
|
the parallel-session caveat above).
|
|
- **`REUSE.md`**, if a shared helper or pattern moved (same commit).
|
|
- **`OPEN-ITEMS.md`** — every finding, with a number.
|
|
- **Root `STATUS.md`** — at the end of every session in which something shipped, broke or was
|
|
decided. It is a **view** of `OPEN-ITEMS.md`; nothing may exist only there. One screen, written for
|
|
the operator in plain language, and deliberately **not** `CONTEXT.md`.
|
|
- **The capability map** (`documentation/architecture/00-capability-map.md`), if a capability's
|
|
status changed — with its new evidence citation.
|
|
- **`python3 scripts/unproven.py --summary`** — one line per status, and the not-walked total. Run it
|
|
at the end of any session that shipped, broke or proved something, and **say in the report if a
|
|
number moved**. It exists because "which claims are unproven?" was answerable only by a person
|
|
reading a page: a session asked for "the nine grey claims" could not determine which nine and
|
|
rightly refused to guess (R-326). *Nine was real and answered a different question — it is the
|
|
count of claims the 2026-08-09 pass DOWNGRADED. Not-walked is 32 of 55.* A status that moves
|
|
without anyone noticing is how the picture stops being true.
|
|
- **Confirm your own last push's CI run went green, by run ID.** CI emails on failure, which is a
|
|
PUSH signal; this is the PULL check that catches a lost, filtered or unread mail. Quote the run id
|
|
and its conclusion, e.g.
|
|
`curl -s "https://gitea.dooplex.hu/api/v1/repos/admin/<repo>/actions/tasks?limit=3"` → match the
|
|
`head_sha` to your commit. An unchecked green is an assumption, not an observation.
|