diff --git a/docs/FRICTION.md b/docs/FRICTION.md index d038954..0fae4f9 100644 --- a/docs/FRICTION.md +++ b/docs/FRICTION.md @@ -117,6 +117,41 @@ _(append new raw signals here; the next kaizen review consumes them)_ line must be a classified, expected change) before accepting any "presentational-only" restructure; consider a helper script. +- `[friction]` **ansible-lint `var-naming[no-role-prefix]` rejects the ADR-021/022 + `access__*`/`backup__*` cross-role field names** (2026-06-14): building the first + service role's records (`reverse_proxy`), adding the ADR-mandated `access__*` / + `backup__*` data to `defaults/main.yml` failed lint — the rule requires every role var + to start with `_`, and ansible-lint 24.x has **no per-prefix allowlist**. The + double-underscore `reverse_proxy__*` namespace passes (starts with `reverse_proxy_`), + but the deliberately shared `access__`/`backup__` names don't. Resolved with inline + `# noqa: var-naming[no-role-prefix]` per var (keeps the rule enforced elsewhere). This + **will recur in every service role**. → decide a project-wide policy before the next + service role: a documented `.ansible-lint` stance, a sanctioned noqa snippet baked into + the `make new-role` scaffold, or reconcile the convention. First collision because + `reverse_proxy` is the first built service role. + +- `[gotcha]` **Molecule CAN exercise tag-propagation, but only with a tagged converge + + full-then-partial sequencing** (2026-06-14): closing part of the 2026-06-14 `apply: + {tags:}` signal ("Molecule converges untagged, so it can't catch tag-propagation"). Added + a second converge play (`include_role` with `apply: {tags: [config]}` + a fresh user) + and an assertion, then proved the fix with `molecule converge -- --tags config`. Caveat + learned the hard way: a partial-tag run on a **fresh** instance fails on cross-concern + deps (a `config` task needs `git`, installed by the `packages` concern), and untagged + pre_tasks (test-user creation) get filtered out — so the realistic test is **full + converge → partial re-run** (idempotent), and harness pre_tasks need `tags: [always]`. + → adopt the tagged-converge-play pattern for any role with concern subsets; this is the + CI check the prior signal asked for, in Molecule rather than `make deploy`. + +- `[recurring]` **ADRs claim cross-doc reconciliation they didn't actually perform** + (2026-06-14): ADR-024's Status + Consequences asserted "ADR-017 prose that mentioned + Traefik is updated to read Caddy" — but ADR-008/017/019 + CAPABILITIES still said + Traefik; the rename was left half-done across the doc set and the ADR over-claimed its + own follow-through. Surfaced only by a full-repo `grep Traefik` during `/review-repo`. + Same shape as the deferred-decision-goes-stale signal (a decision lands in one place, + its promised ripple edits don't). → candidate `repo-scan.py` check: when an ADR's text + asserts "X is updated to Y" / supersedes a named tool, flag remaining occurrences of the + old name (or verify the claimed edit landed) — the structural cousin of `stale-deferred`. + --- ## Kaizen reviews — decisions ledger