docs: add the neckbeard handoff document (field-test results)
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>
This commit is contained in:
Thore Cimbal
co-authored by
Claude Fable 5
Claude Fable 5
parent
c481165ab4
commit
28e1843e8d
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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` |
|
||||
Reference in New Issue
Block a user