management/docs/sources/migration/neckbeard-uebergabe-feldtest.md

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