ship-lesson

Draft → polish gate → Skool upload → independent fetch confirm. Each lesson ship is one atomic run. Parallel ships against the same session are forbidden (see memory: no parallel browser writes - DOM-mutation agents silently drop writes).

Steps

1. Lint + polish (gate)

const draft = readFileSync(draft_path, "utf8");
const polish_result = await polish(draft, { max_turns: 3 });
if (polish_result.score < 1.0) {
  // polish_result.score < 1.0 means it required a rewrite or still failed
  append("chain", { run_id, skill: "ship-lesson", action: "polish-gate",
                    polish_score: polish_result.score, blocked: true });
  if (polish_result.score === 0) throw new Error("polish-gate-failed; aborting ship");
}

score === 0 hard-aborts. score === 0.5 (fixed on retry) proceeds with the rewritten draft, not the original.

2. Upload (serialized)

Shell to state/bin/skool/upload-lesson.sh with the polished draft + cover URL. The script owns the playwright session.

3. Independent fetch

After upload claims success, fetch the lesson URL via a separate playwright run and extract the rendered title + first paragraph. Compare against expected - actor ≠ auditor.

4. Log + score

score("ship-lesson", run_id, {
  score:
    shipped && fetched_matches ? 1.0 :
    shipped && !fetched_matches ? 0.0 :   // silent data loss
    0.0,
  polish_score: polish_result.score,
  lesson_url,
  fetched_title_matches: fetched_matches,
  primary_issue:
    !shipped ? "upload-failed" :
    !fetched_matches ? "content-drift-after-upload" :
    null,
});

Fetch-mismatch scores 0, not 0.5. A "successful upload" that lost content is the exact failure mode certificates-only operation hides.

Gotchas

• Never parallelize. Memory: no_parallel_browser_writes. Fan-out

across lessons = one serialized ship-lesson call per lesson.

• Cover image URL must already be CDN-hosted (by image skill). Raw

local paths fail silently on Skool side.

• skool-auth-restore.sh runs first if the session is stale.

Graduation

Sidecar at state/bin/skool/upload-lesson.sh. Skill page owns the polish gate + fetch verification; the script owns the browser mechanics.

Rubric

criteria:
  - name: polish_gate_handling
    kind: deterministic
    check: "The 'chain' log for the 'polish-gate' action correctly reflects 'blocked: true' if polish_result.score < 1.0, and aborts if polish_result.score === 0."
  - name: upload_and_fetch_integrity
    kind: deterministic
    check: "The final score for 'ship-lesson' is 1.0 only if both 'shipped' and 'fetched_matches' are true, yielding 0.0 otherwise."
  - name: no_parallel_writes_observed
    kind: judge
    check: "Review logs or system output to confirm no simultaneous 'ship-lesson' executions against the same session, adhering to the 'no_parallel_browser_writes' constraint."

ship-lesson - loader

Per-turn rules for the ship-lesson skill. Full reference: state/skills/ship-lesson/SKILL.md. Do not skip these.

Critical Rules

• NEVER parallelize ship-lesson runs - memory no_parallel_browser_writes. Fan-out across lessons silently drops writes; one serialized call per lesson
• ALWAYS run polish gate before upload - polish_score === 0 HARD-ABORTS, 0.5 proceeds with the rewritten draft (NOT the original)
• ALWAYS independent-fetch after upload claims success - actor (uploader) ≠ auditor (separate playwright session reads back rendered title + first paragraph)
• Fetch-mismatch scores 0.0, NOT 0.5 - a "successful upload" that lost content is the exact failure mode certificates-only operation hides (primary_issue: "content-drift-after-upload")
• Cover image URL must already be CDN-hosted (by image skill). Raw local paths fail silently on Skool side
• skool-auth-restore.sh runs first if the playwright session is stale

Commands

| ui dashboard | state/skills/ship-lesson/resources/ui.openui | |invoke: state/bin/skool/upload-lesson.sh (graduated script) - invoked AFTER polish gate passes |polish gate: polish(draft, { max_turns: 3 }) |auth restore: state/bin/skool/skool-auth-restore.sh (run first if session stale) |eval log: state/log/evals.ndjson (skill: "ship-lesson")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/ship-lesson/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Score 0.5 means the polished draft (not the original) goes to upload - passing the original after a rewrite poisons the lesson
• An "upload succeeded" toast from the same browser session is NOT verification - must be an independent fetch from a different playwright run
• Cover URL that's a local path will fail silently on Skool - the upload reports success but the lesson renders broken

Self-Test

An agent reading this should correctly:

1. [ ] Refuse to fan out two ship-lesson invocations against the same Skool session?
2. [ ] Score 0.0 (not 0.5) when upload claims success but the independent fetch finds different content?
3. [ ] Pass the rewritten draft (not the original) to upload when polish_score === 0.5?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] ship-lesson: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] ship-lesson: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.