diff --git a/docs/issues/0040-neckbeard-rueckmeldungen-einreichen.md b/docs/issues/0040-neckbeard-rueckmeldungen-einreichen.md index 0428b6e..0d05b2e 100644 --- a/docs/issues/0040-neckbeard-rueckmeldungen-einreichen.md +++ b/docs/issues/0040-neckbeard-rueckmeldungen-einreichen.md @@ -14,7 +14,9 @@ related: > Eigener Akt, bewusst nicht Teil der Migration (Nicht-Ziel im Design). > `gitlab_iid` folgt mit dem ersten Spiegel-Lauf. -Als Issues im neckbeard-Repo (`oss-projekte/ai/neckbeard`) einreichen, +Das fertige Übergabedokument liegt unter +[docs/sources/migration/neckbeard-uebergabe-feldtest.md](../sources/migration/neckbeard-uebergabe-feldtest.md) +— von dort als Issues im neckbeard-Repo (`oss-projekte/ai/neckbeard`) einreichen, mit Feldtest-Evidenz aus Gate 2 des Design-Dokuments: 1. Viele Repos, ein Regelwerk (Lücke 1; hiesige Lösung: ADR-0013) diff --git a/docs/issues/0042-migration-in-betrieb-nehmen-push-spiegel-schedule.md b/docs/issues/0042-migration-in-betrieb-nehmen-push-spiegel-schedule.md index eff20e3..fb0a0b1 100644 --- a/docs/issues/0042-migration-in-betrieb-nehmen-push-spiegel-schedule.md +++ b/docs/issues/0042-migration-in-betrieb-nehmen-push-spiegel-schedule.md @@ -14,8 +14,9 @@ related: > Die Schritte, die nur sorb ausführt (Nicht-Ziele der Migration: > kein Push, kein API-Write durch die Session). -1. Branch `Neckbeard-v0.1.1-migration-1` sichten und nach `main` - bringen; Push über git.lab (Mirror zieht nach). +1. ~~Branch `Neckbeard-v0.1.1-migration-1` sichten und nach `main` + bringen; Push über git.lab (Mirror zieht nach).~~ ✅ Erledigt + 2026-08-11 (Fast-Forward-Merge + Push, von sorb beauftragt). 2. Ersten Spiegel-Lauf ausführen: `python3 scripts/spiegel_issues.py --ausfuehren` (legt 0033–0042 auf GitLab an); danach die vergebenen iids als `gitlab_iid` nachtragen — ab dann meldet diff --git a/docs/sources/migration/neckbeard-uebergabe-feldtest.md b/docs/sources/migration/neckbeard-uebergabe-feldtest.md new file mode 100644 index 0000000..5cfdc7a --- /dev/null +++ b/docs/sources/migration/neckbeard-uebergabe-feldtest.md @@ -0,0 +1,93 @@ +# Handoff to the neckbeard repo — field test results, v0.1.1 + +Written 2026-08-11 at the close of the first real neckbeard adoption. +In English because it is destined for the neckbeard repo, whose +artifacts are English by its own convention. This file is the frozen +handoff record (management repo, `docs/sources/migration/`); carrying +its content into neckbeard issues is tracked as management issue 0040. + +## What happened + +- **Field test** against neckbeard `v0.1.1` + (`823a08cac6b03a47d7e2f661200a49ac6e09d38d`): two sessions on the + `axion1337.chat/management` repo. Session 1 (branch + `Neckbeard-v0.1.1-analyse-1`) produced 17 evidence-backed findings — + read `analysis/REPORT.md` there, especially the + pattern → mechanism → implication table. Session 2 migrated the repo + to neckbeard through **all gates of a size-L undertaking**: Gate 0 + (PROJECT.md), design doc with Gates 1–5, five vertical slices, each + with verification evidence and a human STOP. +- Result: `docs/design/done/2026-08-11-neckbeard-migration.md` on + `main` of the management repo — including the Gate-5 AAR and the + two-way harvest (old approach's value folded into neckbeard before + adoption). + +## Relevant for versioning (ADR-0006) + +ADR-0006 names "the first completed size-L run in a real project" as +the sensible trigger for considering `v1.0.0`. **That run now exists +and is documented.** The schema and rule set survived it, with the +extensions below — worth weighing before any 1.0 decision. + +## Feedback items, each with field evidence + +Reference implementations live in the management repo (`scripts/`, +`schema.yaml`, `docs/components/`); findings F-NNN in the analysis +branch. + +1. **Many repos, one ruleset.** ADR-0001 ends at the repo boundary; a + five-component group has no defined sharing mechanism. Solved + project-side as pointer + deterministic presence check + (management ADR-0013). Evidence: F-011 — 4 of 5 components carried + no instruction file and nothing noticed. +2. **Components artifact.** No artifact type declares "these are the + repos and their canonical names"; slug drift was unrepresentable + (F-008). Project-side: `component` type, filename = canonical slug. +3. **Milestone concept.** No field groups issues by what they pay + into; the project uses milestones on 100% of open issues (F-014). + Project-side: required `milestone` enum on issues. +4. **SHA citations in prose are never resolved.** F-012: six orphaned + citations, mechanically uncheckable. Reference: `pruefe_prosa.py` + (resolution via repo, rewrite-mapping table, optional clones, plus + a curated exemption list — hex words are not always git SHAs: + Authentik uids and Alertmanager silence IDs both matched). +5. **Git-level hygiene is outside the framework's view** while + carrying the project's most sensitive claims (F-002/F-003: 222 + real-clock commits by own identities believed anonymised). + Reference: `gruppenpruefung.py` hygiene check. +6. **External link targets are never checked.** A live doc routed to a + retired tracker (F-005 — eight dead links found in practice). + Deterministic partial solution: a denylist of retired URL patterns; + full reachability checking deliberately rejected (network-bound). +7. **Priority field.** The creation AAR filed it as YAGNI with + "revisit via refinement". Field evidence for the revisit: 71/71 + open issues carry exactly one priority, cleanly distinct from the + milestone ("how urgent" vs "what it pays into"). +8. **`validate.py` rejects directory links** (`[x](dir/)`), which + GitLab renders fine. Opinion question; cost us three pre-existing + "broken" links. +9. **Adopted AGENTS.md has no defined place for project rules.** + Solved as: upstream sections byte-true, then a marked project + section; a byte-compare check against a vendored pristine baseline + (`docs/sources/upstream/`) turns silent framework-file rewrites + into red CI. The baseline answers a real adopter question ("will + agents rewrite AGENTS.md?") — consider making it part of the + adoption path. +10. **ADR duty for permanent exceptions** exists in this project's old + ruleset and proved itself (documented-but-undecided exceptions are + a named failure mode); upstream has no such rule. +11. **A runtime check family beside validate.py.** The project's + Stillstandsprüfung principles held up well and generalize: checks + only from real incidents, "cannot check" is a finding not a skip, + abort instead of silently skipping, project lists read at runtime + never maintained in code. + +## Where to look + +| What | Where | +|---|---| +| Field-test findings + data | management branch `Neckbeard-v0.1.1-analyse-1`, `analysis/` | +| Migration design + AAR | `docs/design/done/2026-08-11-neckbeard-migration.md` (main) | +| Schema extensions | `schema.yaml` (flagged header) vs `docs/sources/upstream/neckbeard-v0.1.1/schema.yaml` | +| New check scripts | `scripts/pruefe_upstream_drift.py`, `pruefe_prosa.py`, `gruppenpruefung.py`, `spiegel_issues.py` | +| Harvested pitfalls | `docs/wiki/stolpersteine/neckbeard-migration.md` |