94 lines
5.0 KiB
Markdown
94 lines
5.0 KiB
Markdown
 
|
# 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` |
|