Lessons into practice

Practical improvements for the next course build: when to act, who owns the outcome, which existing tool to use, and what evidence proves the change worked. The strongest lessons become reusable checks and clearer operating instructions.

Reusable work, measured at its scope: The builder release packages skills, coverage checks, and repeat-setup behavior for reuse across authorized course work. These are delivered tooling capabilities; their financial value depends on measured use and your assumptions. Explore the evidence and ROI scenario →

September 12: verify assumptions inherited from the original design

HumGeo · Historical evidence window: July 27–September 12, 2026. This documents a design-to-publication failure and the controls to adopt; it does not change course acceptance.

Trigger: Reuse an inherited course design, accept a content inventory, or migrate a course to a new publisher.

Observable failure: The article-coverage assumption was embedded in the original adopted design. The July 27 AM-3 amendment stated, “Existing lessons’ articles ARE the video scripts.” Later validators treated membership in the lesson content map as article presence. The native publisher accepted that inventory but selected only records whose content_kind was article. Scripts therefore counted toward the inventory without becoming standalone published articles. September’s enrichment improved the separate 72-page article bank; that narrower result did not establish written instruction across the curriculum, and the enriched source bodies differed from the AP One publication bank.

Missing control: No end-to-end check challenged the inherited definition against actual teaching content and the publisher’s selection. Attachment presence, article-subset validation and embedded-question QC answered different questions, but were treated as support for broader completeness. Accepted source text was not reconciled through export to the learner-visible body.

Implemented control: This lesson records the original assumption and separates content presence, instructional adequacy, article acceptance and delivery. Enforcement still requires implementation and verification. At existing inventory and publication stages, preserve script/article/video distinctions; map curriculum and assessment demands to adequate instruction; and bind accepted source text to exported and served text. Reuse valid material before generating replacements. A word count is a diagnostic, and passing question QC does not establish article acceptance.

Verifier: Use the owning native checks to reconcile required teaching demands, actual content kinds and source-to-export-to-served bodies. Require an explicit disposition for each gap or changed body, even when identifiers are unchanged. A script attachment alone must not prove substantive article coverage; a passing subset must not close the whole population. Record adoption only when those checks run on the intended course and publication inputs.

Evidence: Original AM-3 design assumption · Presence-based inventory · Inventory acceptance and article-only selection · Scoped enrichment PR #69 · Article-validator repair PR #71 · Enriched source bank / AP One publication bank. Repository evidence requires the appropriate access.

September 10: measure remaining scope before choosing work

Trigger: Start or resume a course-building session.

Observable failure: A plan pointer or a passing gate bank can hide unfinished practice, media, writing or delivery populations.

Missing control: The starting checkpoint did not require a complete population census or feed new gaps back into the native plan.

Implemented control: The private builder now requires each population with separate observed, accepted, integrated and served counts. Missing coverage stays UNMEASURED. Reports put remaining scope first, new gaps require a plan amendment, and eligible content work outranks unrelated scaffolding. Decision requests state what they unblock, the authorized default and its cost. The installer bundles verified skills and their resources while preserving existing installations.

Verifier: Run the private package’s test_coverage.py and test_local_builder.py, then validate the session report with course-runbook/check.py --report report.json --checkpoint course-state.json. These checks validate the tooling and declared consistency; current native receipts still establish course acceptance. Agent entry point (Alpha access).

September 14: make native terminal evidence reusable

Trigger: Reuse a native course operation across a later wave or course.

Observable failure: A plan, merged change or successful process exit can be mistaken for a completed native operation.

Reusable control: Keep the existing course-owned launcher as the mechanic and separate its three terminal boundaries: capture the prior state, execute once and read back the write, then replay the identical operation and require a zero-write receipt.

Acceptance evidence: Each boundary must carry the packet's sealed digest, exact input fingerprint, private receipt, checkpoint and complete logs. verified is the population read back by that invocation; writes is that invocation's writes, so a resumed run may have fewer writes than verified. The replay must report zero writes and the expected verified population. This proves the native operation's idempotent readback; it does not prove cold QC, learner acceptance, activation or release.

Recovery: A client observation timeout with a confirmed live native handle requires reattachment and terminal readback, never a restart. A terminal native refusal or failure follows the packet's recovery route and preserves its checkpoint.

Scope: Operation receipts establish the operation's evidence boundary; they do not establish completed course QC, learner acceptance, activation or release. Each stage requires its own evidence.

September 10: put the twelve lessons into practice

Source window: the September 9–10 HumGeo two-seat retrospective, ending at the recorded stand-down. Apply these actions at existing dispatch, review, integration and release decisions. They describe next-build practice; current course standing remains on the HumGeo page.

Wired code: the Course Builder launcher runs the existing checkpoint consistency check. It checks declared scope, dependencies, retry reasons, job evidence references, usage and ETA support; it does not open the referenced receipts or verify native acceptance. Guidance shipped: eight decision cards cover all twelve findings. Operating adoption pending: the actions below still need evidence from the next build.

Eight existing decision cards, with accountable roles and acceptance evidence.
When to act · accountable role	Implementation to adopt · acceptance evidence
Reconcile the selected source before scaleLessons 1, 3, 9, 12 · Trigger: broad dispatch or a changed selected-source baseline. Owner: orchestrator.	Action: use the existing selector to classify every selected obligation and its teaching, placement and integration dependencies. Keep release milestones fixed when scope changes. Use: `course-deficit-burndown`, `phase-bank-validation`. Accept when: the selected-source receipt binds the exact source, actual form members, reusable native acceptance and one owner per remaining group.
Dispatch a feasible complete groupLessons 2, 3, 5, 7, 11 · Trigger: generation, article work or repair QC. Owner: complete-form owner.	Action: reserve the actual target; read the full teacher; check current placement, concept limits and the exact request mode before spending. Use: `factory-batch-dispatch`, `item-pipeline`, the selected native article validator. Accept when: free checks pass on the intended request, the scoped envelope is recorded, and a returned teaching body is accepted before dependent items rely on it.
Return one usable review of the changed batchLessons 6, 7, 12 · Trigger: a bounded changed group is ready. Owner: independent reviewer; author resolves findings.	Action: return substantive findings together and reuse unchanged approvals under the native request and provenance rules. Finish learner-facing cleanup before final QC. Use: `one-round-review`. Accept when: one verdict binds the changed bytes, closes its findings and can be consumed directly by the integrator without another routine approval relay.
Diagnose the premise before another attemptLessons 4, 5, 6, 11, 12 · Trigger: a native failure, especially a repeated reason. Owner: author and independent reviewer.	Action: preserve the full response and distinguish content, teaching, request, context and verdict defects. Resolve the shared cause within the native contract. Use: `item-regen`, `item-class-precedent`. Accept when: the next attempt names a changed cause or an authorized bounded diagnostic purpose, respects native limits, and closes the prior envelope's calls and outcomes.
Close the form through integrationLessons 2, 3, 6, 7 · Trigger: an accepted group reaches the source owner. Owner: form owner and single integrator.	Action: consume exact approved records with current input bindings; transfer the whole group if a dependency stalls. Recheck affected inputs when they change. Use: `land-a-change`, `phase-bank-validation`. Accept when: required recall, application, teaching and placement dependencies are integrated and the native whole-form receipt passes on the joined source.
Prepare the release interfaces alongside contentLessons 8, 9 · Trigger: content work begins, then the final-source join. Owner: authorized release owner.	Action: inspect actual merge dependencies and the native publication and learner sequence early; bind one final digest and one remote writer. Use: `land-a-change`, `publish-course-dark`, `course-qc-gauntlet`. Accept when: each required source, dark-readback, hosted-QC, learner and release outcome has its own verified receipt in the owning sequence.
Report outcomes, evidence and scoped costLessons 9, 10, 11, 12 · Trigger: an existing milestone update or handoff. Owner: orchestrator.	Action: report fixed outcomes, the oldest dependency and observed, peer-reported or proposed job state. Reconcile available provider/Hermes usage and QC ledgers by scope. Use: `course-deficit-burndown` and the existing checkpoint check. Accept when: completion and running-job claims have matching receipts; billed cost, estimates and gaps stay separate; an ETA has a reconciled dependency chain and duration evidence or reads `UNMEASURED`.
Transfer a compact, resumable resultLessons 7, 12 · Trigger: owner pause, interruption, transfer or no sanctioned work remaining. Owner: current orchestrator and receiving owner.	Action: honor the pause and preserve current refs, complete and remaining groups, reservations, native job IDs and recovery boundaries. Use: `course-deficit-burndown` and the existing checkpoint. Accept when: the handoff names the next dependency and spend gaps, preserves failed evidence, and permits continuation without duplicate submissions or a new approval hierarchy.

Verify adoption: inspect the next build's existing milestone receipts against these rows. A shipped card or a consistent checkpoint alone does not demonstrate changed operating behavior, course acceptance or savings.

Retrospective gateway · Private agent runbook · Decision cards (Alpha access).

Prove the complete route before scaling the next course

2026-09-09 · HumGeo · Evidence window: September 1–9, including the saved course pause and separately completed video uploads.

Trigger: A course campaign expands from pilots into parallel authoring, review, integration and publication.

Observable failure: Drafts, individual passes and prepared patches accumulated while complete forms and the final publication remained open. Item-only QC missed article failures; repeated review rounds, local/native contract mismatches and approval-file handoffs consumed effort without establishing the next outcome.

Missing control: Complete input context, population-level validation and a defined handoff to the next owner were not consistently present before scale. Transport speed and worker activity obscured acceptance and integration.

Implemented control: Successful HumGeo lanes used emit/judge/render pilots, native population checks, coupled whole-form repairs, exact accepted-object transfers and installed-helper verification. Routine authority allowed mechanical consumption of existing approvals. The linked retrospective turns these demonstrated methods into a staged next-course playbook; its team and flow-metric recommendations remain proposals, not new policy.

Verifier: The investigation matched h34’s 12 recorded integration objects and h41’s six new objects to immutable Git blobs, checked 51 supporting file hashes, and joined 191 video upload rows to reviewed/local/served hashes. The page records separate limits for each example and links authenticated repository landings. None of these results grants final-course publication or learner acceptance.

Use it: Retrospective gateway · Private agent runbook · Structured plan (Alpha access) · Dated evidence index (Alpha access).

28 review rounds on one branch; now one

2026-09-08 · HumGeo · Historical source window: 2026-09-04 through 2026-09-08.

Trigger: Closing review of the PP100 practice-item branch.

Observable failure: The postmortem records 28 closing-review rounds. Sixteen (12–27) were one-finding-per-round loops on the same code paths. It reports that nothing wrong landed and estimates about twelve hours spent where a class-level fix and a stated contract could have closed the work in two rounds.

Missing control: The brief stated no review boundary; fixes closed the reported cell instead of its class; repeated findings did not trigger closure by contract. All local checkers shared one uid and filesystem, hiding two environment blockers: evidence available on one laptop and tests that behave differently under CI’s root user.

Implemented control: The one-round-review skill adds a deterministic pre-review sweep, a boundary block for review briefs, and a class-close receipt from round 2. A registered PreToolUse gate refuses matching closing-review dispatches without those prerequisites; explicit waivers are ledgered.

Verifier: Inspect the head-bound sweep receipt and review boundary; from round 2, inspect the class-close receipt’s set coverage, contract sentence and scope refutations. The skill, gate and hook registration were read on 2026-09-08. This lesson grants no PP100 landing or lifecycle credit.

The bar (owner’s words): “the goal is not to just 'have fewer rounds;' the goal is to achieve the same quality result with only one round instead of 28.” One round is the target, not a measured guarantee for future reviews.

Receipts: PP100 PR #1036. Supporting internal records: POSTMORTEM-PP100-28-ROUNDS-20260908.md, one-round-review skill, and one-round-review-gate.py. These machine-local records have no verified public URLs.

How a lesson earns a place here

trigger → observable failure → missing control → implemented control → verifier

Build inside the canonical sequence. Trigger: downstream work begins while upstream authority is unresolved. Observable failure: multiple artifacts can each look green while no one can say what closes the course. Missing control: one active lifecycle state with a defined postcondition. Implemented control: the ASAP route is content → p3 → p5 → p6 → p7 → p8, and each course displays only its re-earned position. Verifier: every handoff returns the named state or phase, canonical surface, production verifier, residue, owner, and next phase.
Stop legacy automation at a new boundary. Trigger: an older retry continues after the owner replaces the operating sequence. Observable failure: work that belongs after scope and inventory is pulled back into stabilization. Missing control: retry scope was not rebound to the new gate. Implemented control: the gate remains on hold until the retry is stopped or rescoped. Verifier: live issue readback shows a terminal writer-free transaction before the next gate opens.

Lessons — the 24 hours after the Psych sync (2026-08-31 → 2026-09-01)

Source window: verified receipts and event rows from the afternoon of 2026-08-31 through 2026-09-01.

Confirm the shipping route with the operator, then verify the repository. Trigger: a course needs a current TimeBack publication route. Observable failure: an operator account can omit executable machinery; the 2026-09-01 check surfaced two live precedents built outside the original runbook, while repository bytes exposed an eight-stage pipeline, a post-publication QC loop, and a publishing SDK. Missing control: a source-bound route inventory. Implemented control: ask one scoped route question, then inspect pinned source and evidence bundles before selecting a process. Verifier: the pinned AP Biology and AP Environmental Science publication bundles plus their exact repository SHAs, observed 2026-09-01.
Prefer measured live state when a designed process has no production receipt. Trigger: a designed route and a live-proven route disagree. Observable failure: across these four courses, the comparison found no published-course receipt from the original machinery, while the fleet's four-task tail carried two verified precedents. Missing control: a precedence rule based on measured delivery. Implemented control: the ASAP edition adopts the proven tail, preserves the quality bars, and restores the original ceremony at the first real student enrollment. Verifier: the AP Biology and AP Environmental Science task-one-through-task-four receipt tables and the machine-checkable ASAP contract.
Publish dark before course-level QC, then keep enrollment closed until convergence. Trigger: the acceptance instrument can evaluate only a published course. Observable failure: pre-publication checks cannot inspect the live course; the precedent course entered active service at a 73.62% strict pass rate and improved after publication. Missing control: isolation between technical publication and learner access. Implemented control: publish with zero student enrollments, run the live judge-remediate-republish loop to the declared bar, and broaden access only after acceptance. Verifier: TimeBack status and enrollment readback followed by a cold course-QC result at the declared bar.
Tie every safeguard to a known failure and every cut to a return trigger. Trigger: a faster route proposes removing ceremony. Observable failure: two approved drops were nearly resurrected, stale local trees could overwrite live fixes, deleted identifiers cannot be safely reused, and failed embedded QTI can appear complete to learners. Missing control: an explicit failure-to-control map and restoration boundary. Implemented control: retain the denylist, pre-publish drift refusal, deleted-ID non-reuse, and QTI validation; restore the full ceremony at first enrollment. Verifier: dropped-ID live readback, the drift check's blocking result, a fresh versioned identifier, the QTI known-bad fixture, and the enrollment transition checklist.
Crosswalk repository layouts; do not reorganize working trees. Trigger: the fleet's stage model differs from a course repository's existing layout. Observable failure: moving files would invalidate sealed plans, executor references, and live tooling. Missing control: a non-invasive stage map. Implemented control: a one-page crosswalk maps each fleet stage to the artifacts where they already live, with zero moves. Verifier: exact live GitHub path reads for every mapped row and a zero-rename repository diff.
Bind freshness to live remote state and live run artifacts. Trigger: a local clone is offered as evidence of current state. Observable failure: APWH exposed a mismatch between local-clone state and live GitHub. Missing control: remote provenance and active-session readback. Implemented control: bind repository facts to an exact GitHub SHA and read running-session state from its own artifact directory. Verifier: authenticated remote commit lookup, exact-byte comparison, and the active run receipt's own timestamp.
Rebuild review evidence from source after contamination or a false negative. Trigger: a small, trusted mapping document is assembled from search evidence. Observable failure: review found invented directory names, a dressed-up mapping, a false gap caused by a narrow search term, and a false reviewer finding caused by a corrupted evidence pack. Missing control: independent review against a clean source pack. Implemented control: rebuild ground truth from source, test both present and absent paths, and review until the findings close; never patch a contaminated pack. Verifier: fifth-round approval on a rebuilt pack plus exact path-existence probes.

What changed

A receipt must identify the exact bytes it judges. Transport success without a current-byte fingerprint is not acceptance proof. HumGeo therefore re-earned 429 current-byte passes; merged PR #45 now supplies the sealed candidate-only plan for the remaining 332-row cohort, but its zero-action receipt does not claim execution.
Data and machinery get separate dispositions. Inputs may survive even when the local walker, applier, voter, or campaign runner that touched them is void. Purge and replacement evidence.
Green mechanics are necessary, not sufficient. Historical APWH PR #791 closed unmerged when native placement won. The first two model-backed Faultless Bar legs then ran and failed closed; coverage and a completed run still do not substitute for two passing, exactly agreeing post-repair legs. Current acceptance issue.
A receipt is not a canonical admission. APUSH canon is 38 of 249: 36 legacy dual-review plus 2 server-strict. Eleven additional successor records have receipts but remain outside the committed ledger until the fleet lands them. Canonical ledger.
Milestones must open their own receipts. Psychology EBQ admitted two items but closed zero buckets, so it earns no serving credit. Audit evidence.
Definition of done changes the critical path. The active milestone is a named course that Learning Science can access and walk. Blueprint coverage remains an internal planning measure; an evidence packet, duplicate generation QC, rebuilt grader calibration, unnamed pre-review signoff, and production release do not gate the handoff.

Factory-canonical operating rules

Open the durable cross-course audit findings.

Read the committed factory contract before acting. If the route exists, use it exactly. If it does not, file the gap; do not bridge it locally.
Bind inherited factory evidence instead of repeating it. Generation-time QC and hosted grader calibration keep their value when the exact candidate and provenance are linked; an empty downstream folder does not erase them.
Measure the review denominator before authoring. Pin blueprint scope, compute current coverage, and generate only the highest-value missing work. Never shrink the denominator after seeing a low score.
Keep states separate. Prepared, factory-accepted, merged, deployed, and released are different claims with different evidence.
Unknown stays unknown. Missing provenance or an unread receipt blocks credit; prose cannot fill the gap.
Approvals are scoped. Investigation, CI success, or a prior owner go does not authorize a new write, paid run, filing, merge, deletion, or release.
One writer owns each lane. Other agents may inspect and report, but they do not mutate the same checkout or state.

Safe cleanup sequence

Quarantine only exact SHA-verified targets after checking for live processes and locks.
Prove the canonical replacement or record a factory contract gap.
Retire any status mark that depended on the old machinery.
Delete only owner-approved rows whose replacement preconditions passed.
Run the residue scan twice and keep remaining blockers explicit.

Current posture: the 16-row purge manifest is approval-gated. No hand-rolled target should be deleted merely because it appears on the list.