Thore CimbalandClaude Fable 5
28e1843e8d
Frozen handoff record for the upstream repo, English per neckbeard's own artifact convention: the completed first size-L run (the ADR-0006 v1.0.0 trigger), eleven feedback items each with field evidence and reference implementations, and a where-to-look table. Issue 0040 now points at it; go-live item 1 in issue 0042 is ticked off by this push. Size S under the granted exception - one deliverable, no design decisions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
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` |
|