Skip to content

docs(spec): §89 distillation epic scoping + roadmap status sweep + /dogfood template#1766

Merged
noahgift merged 1 commit into
feat/spec-85-p2e-findingsfrom
feat/spec-89-distillation-scoping
May 17, 2026
Merged

docs(spec): §89 distillation epic scoping + roadmap status sweep + /dogfood template#1766
noahgift merged 1 commit into
feat/spec-85-p2e-findingsfrom
feat/spec-89-distillation-scoping

Conversation

@noahgift

Copy link
Copy Markdown
Contributor

Summary

Closes the §80-class spec stack for MODEL-2 v1 ship. Three artifacts:

  1. SPEC §89 — distillation epic scoping (path to AC-SHIP2-003-STRICT via PMAT-683/684, multi-week, out of v1 scope)
  2. albor-370m-roadmap.md sweep — P3 status table updated to reflect actual ship state; new P4 distillation epic section; new §7 post-§88 shipping plan
  3. /dogfood verdict template — pre-author the post-publish QA checklist so the structure is ready when operator runs /dogfood after apr publish

§89 highlights

  • Why distillation works at this scale: Stanton et al. 2021's 5× token-reduction claim → 9.88B Chinchilla target → 2B tokens via distillation → 43h GPU = fits 48-hour iteration budget.
  • Existing infrastructure is already in-tree: aprender-train::distill + apr distill CLI + 7B Q4_K teacher load + §86-gated init load. No new framework code needed.
  • PMAT-683: teacher selection + pull (4-6h scope, low risk).
  • PMAT-684: distillation training dispatch + evidence (~43h GPU + 8h operator, 70% probability).
  • PMAT-685: hardening (deferred — multi-teacher / curriculum / LR cycling / layer-wise losses).
  • Sequencing (§89.7): v1 MUST ship + /dogfood GO + at least one external consumer validation BEFORE v2 dispatches. Distillation IS the stack — running it before v1 is shipped means testing the pipeline against an unproven training pipeline.

/dogfood template highlights (8 sections)

Pre-authored sections for operator to fill in post-publish:

  1. Provenance + identity (date, operator, HF commit sha, version)
  2. Pull + install verification (the dogfood entry point — clean cargo install + apr pull)
  3. Inference smoke (apr run with the fibonacci prompt)
  4. Inference benchmark (apr bench ≥ 200 tok/s acceptance vs P2-E's 315.6)
  5. Format export round-trip (GGUF + SafeTensors, llama-cli sanity)
  6. apr qa 8-gate sweep
  7. /dogfood 12+5-gate sweep (the apr-cookbook skill)
  8. Independent consumer test (the §89.7 validation-by-use gate)

Plus a final-verdict section (GO / WARN / NO-GO) and a post-verdict actions decision tree.

Stacked on PR #1754

Base: feat/spec-85-p2e-findings. Depends on the §88 framing. Will auto-rebase to main after #1754 lands.

What this PR does NOT do

  • ❌ Does NOT actually run /dogfood (template only — execution gated on P3-C-exec)
  • ❌ Does NOT dispatch PMAT-683/684 distillation (43h GPU; explicit user authorization required)
  • ❌ Does NOT close ship-model-2-spec.md (stays at 95% per §88 until P3-C-exec lands)

Refs

🤖 Generated with Claude Code

…ogfood template

Closes the §80-class spec stack for MODEL-2 v1 ship. Three artifacts:

## §89 — distillation epic scoping (SPEC)

Documents the path to AC-SHIP2-003-STRICT (val_loss ≤ 2.2) via
Qwen-7B teacher distillation. ~110 lines covering:

- 89.1 Why distillation works at this scale (Stanton et al. 2021's
  5× token-reduction claim → 9.88B → 2B tokens → 43h GPU fits the
  48-hour iteration budget).
- 89.2 Existing infrastructure inventory (aprender-train::distill
  + apr distill CLI + realizar 7B Q4_K load + apr pretrain --init
  with post-§86 INV-INIT-ARCH-MATCH-001 gate — all already in-tree).
- 89.3 PMAT-683 teacher selection + pull (4-6h scope).
- 89.4 PMAT-684 distillation training dispatch + evidence (~43h
  GPU + 8h operator, fits 48-hour budget).
- 89.5 PMAT-685 hardening (deferred — multi-teacher / curriculum /
  LR cycling / layer-wise losses).
- 89.6 Out-of-scope alternatives explicitly rejected (9-day compute,
  1.5B+ arch, multi-host distributed).
- 89.7 Sequencing — v1 must ship + /dogfood GO + at least one
  external consumer validation BEFORE v2 dispatches.
- 89.8 Discharge criteria.

## Roadmap status sweep

`docs/specifications/aprender-train/albor-370m-roadmap.md` P3 table
updated to reflect actual ship state:

- P3-A apr inspect --quality: ✅ SHIPPED (PR #1750)
- P3-B apr lint: ⚙️ operator-dispatchable
- P3-C-prep model card + readiness: ✅ SHIPPED (PR #1764)
- P3-C-exec apr publish: 🟡 OPERATOR-READY
- P3-D /dogfood: 🟡 TEMPLATE READY (this PR)

Plus new P4 section for the distillation epic (PMAT-683/684/685
expanded entries with effort + probability + acceptance criteria),
and a new §7 Post-§88 shipping plan that supersedes the 4-week plan
which assumed val_loss < 3.0 was achievable within iteration budget.

## /dogfood verdict template

`docs/dogfood-templates/albor-370m-v1-dogfood-template.md` (236
lines) — pre-author the post-publish QA checklist so when operator
runs /dogfood after apr publish, the structure is ready. 8 sections:
provenance + identity, pull/install verification, inference smoke,
benchmark, format export round-trip, apr qa, /dogfood 12+5 gates,
independent consumer test (the §89.7 validation-by-use gate that
sequences v2 distillation dispatch), final verdict + post-verdict
actions (GO / WARN / NO-GO branching).

## What this PR does NOT do

- Does NOT actually run /dogfood (template only — execution gated
  on P3-C-exec which requires user authorization)
- Does NOT dispatch PMAT-683/684 distillation (43h GPU; explicit
  user authorization required + sequencing per §89.7)
- Does NOT close ship-model-2-spec.md (stays at 95% per §88 until
  P3-C-exec lands)

## Stacked on PR #1754 (SPEC §84-§88)

Base: `feat/spec-85-p2e-findings`. The §89 scoping depends on the
§88 framing. Will auto-rebase to main after #1754 lands.

## Refs

- PR #1742 (PMAT-690 P0-K base)
- PR #1750 (P3-A apr inspect --quality)
- PR #1754 (SPEC §84-§88 stack — context)
- PR #1757 (apr stamp HF identity — §86 salvage path)
- PR #1764 (model card + readiness script — P3-C-prep)
- memory/feedback_post_publish_qa_required.md (#29)
- memory/feedback_publish_readiness_preflight.md (#37)
- Hinton et al. 2015 (arXiv:1503.02531) — distillation foundations
- Stanton et al. 2021 (arXiv:2106.05945) — 5× token-reduction claim

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@noahgift noahgift merged commit e910ca1 into feat/spec-85-p2e-findings May 17, 2026
1 check passed
@noahgift noahgift deleted the feat/spec-89-distillation-scoping branch May 17, 2026 15:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant