Skip to content

t1k:cocos:playable:stdlib-harvest

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: consumption, harvest pipeline, harvest pla, repoint, stdlib ledger, stdlib-harvest

/t1k:cocos:playable:stdlib-harvest
[--resume-from <stage>] [--stop-after <stage>] [--repo <owner/name>]

Runs the harvest pipeline: find the reusable capabilities already sitting in the fleet’s playable-ad repos and move them into The1Studio/cocos-stdlib as @playablelabs/* packages — then record what the run learned so the next one is cheaper.

This skill decides nothing about packaging. From S5 onward each accepted candidate goes to t1k-cocos-base-stdlib-contribute, whose Steps 0-2 still own the scope gate and the granularity decision. What this skill adds is the pipeline around that skill: an org-wide inventory, a symbol fingerprint (S4) that finds duplicates mechanically rather than by reading, a purity and equivalence gate (S6a/S6b) that makes a dedupe claim falsifiable, and a ledger that makes recurrence countable.

references/contracts.md is the interface freeze — every script CLI, JSON shape, exit code, the run-draft file and the evidence layout. assets/failure-codes.json is the catalogue every failure code comes from (D20). Neither is restated here; a reference cites them by section.

CheckWhy
Session cwd is the cocos-stdlib clone, on main, tree cleanThe ledger, clone index and report are written there; S11 branches from it
Harvest deps installed: bun install --frozen-lockfile --ignore-scripts --cwd .claude/modules/playable/skills/t1k-cocos-playable-stdlib-harvest/scriptsts-morph, jscpd and ajv are pinned; a missing one is exit 2, never a heuristic fallback. Bun ≥1.4.3, gh and git ≥2.35 are REQUIRED prerequisites, declared with this step in install.json. The test suite has its own pin (tests/package.json, fast-check) — bun test "tests/*.test.cjs" needs that one installed too, or it fails with Cannot find module 'fast-check' (references/contracts.md § DEPS/DEPS_TESTS)
gh auth status succeeds and reaches The1StudioS0 lists the org, S7’s stop check calls gh pr list, S11 opens the PR
STDLIB_HARVEST_DISCORD_WEBHOOK_URL is setS12 has no fallback to DISCORD_WEBHOOK_URL (D8). Check presence, never print the value
A user is presentFive stages ask — S0, S9, S10, S12, S14; a non-interactive session stops at the first gate
Agent/Task is available (not a routed hop, not a fork)S3 onward spawns on nearly every row — see “This skill runs in the main session (D17)” below. harvest-clone.cjs clone (S1) itself refuses with S1-NO-FANOUT when MR_SPAWNED=1, before any side effect (#579); a forked skill body carries no such marker, so this row’s fork half is prose-only, self-checked by the session

One repo per session. A run is scoped to a single repo at a single SHA; a second repo is a second session with its own runId, its own branch and its own ledger row.

effort: high with no context: fork — a forked skill body loses Agent, and validate-skill-context-fork-spawn-usage.cjs rejects fork + spawn outright. The stage table below spawns on nearly every row, and the five human gates are direct AskUserQuestion calls, so a context: key here is not a tuning mistake; it is the pipeline failing to run at all. t1k-cook has the same shape for the same reason.

Never edit this skill within its own run. S13’s tier-2/3 fixes leave via that run’s sync-back PR; the body you are executing is the body you would be changing, and the change cannot be validated by the run that depends on it.

Stages run in execution order — the numbering is the ledger’s key, not the run order. S6b follows S7 because purity (S6a) and extraction (S7) must both happen before an equivalence spec can be written against the extracted original.

#StageToolReferenceLedgerFailure codes
S0Inventory the org: Cocos 3.x repos not yet harvested at HEADharvest-preflight.cjs, harvest-inventory.cjsreferences/s00-inventory.mdS0S0-GH-AUTH S0-INACCESSIBLE S0-NO-WEBHOOK-CONFIG
S1Sparse-clone the chosen repo at its SHA; open the run draftharvest-clone.cjsreferences/s01-clone.mdS1S1-CLONE-FAILED
S2Guard: confirm on the working copy that this is a Cocos 3.x projectdetect-cocos-project.cjsreferences/s02-guard.mdS2S2-NOT-3X
S3Chunked candidate scan + six read-only audits into evidence/stdlib-candidates.cjs + six auditsreferences/s03-audits.mdS3S3-AUDIT-FAILED S3-CEILING-DROP
S4Fingerprint every symbol; compare prior → stdlib → fleetclone-fingerprint.cjs, near-dup-report.cjsreferences/s04-fingerprint.mdS4S4-TS-PARSE
S4bClassify game-foundation overlaps as REUSE-via-portenumerate-subsystems.cjsreferences/s04-fingerprint.mdS4b(none — a documentary read)
S5Scope-gate, label and cap the candidate set for the gatecoupling-probe.cjs + (main session) + reason-loss-check.cjsreferences/s05-classify.mdS5S5-SCOPE-REJECT
S6aPurity check — does the symbol’s closure reach cc?purity-check.cjsreferences/s06a-purity.mdS6aS6A-CC-COUPLED
S7Extract and scaffold in a package worktree, stopping after Step 6contributor agentreferences/s07-extract.mdS7S7-STOP-VIOLATED S7-VERIFY-FAILED
S6bDifferential equivalence test, generated then run, then reconciled into the recorddiff-test-generate.cjs, diff-test-run.cjs, s6b-verdict-check.cjsreferences/s06b-equivalence.mdS6bS6B-DIVERGENT S6B-INCONCLUSIVE S6B-RECORD-STALE
S8Gatekeeper verdict per candidate, up to 3 roundsverdict-check.cjs + gatekeeper agentreferences/s08-gatekeeper.mdS8S8-REJECT S8-ROUND-CAP
S9Human approval table — nothing passes it unapprovedAskUserQuestionreferences/s09-human-approval.mdS9S9-HUMAN-REJECT
S10Resume the contributor, open the package PRs, confirm publishcontributor agent + t1k-ci-watcherreferences/s10-contribute.mdS10S10-CI-RED S10-PUBLISH-MISSING
S11First ledger write; overlap register; open the S11 PRharvest-ledger.cjs + reason-loss-check.cjsreferences/s11-record.mdS11S11-SCHEMA-INVALID
S12Post the run summary to the Discord threaddiscord-notify.cjsreferences/s12-discord.mdS12S12-NO-WEBHOOK S12-POST-FAILED
S13Tier every lesson, emit markers, sync back, set final statusharvest-ledger.cjsreferences/s13-self-improve.mdS13S13-SYNCBACK-FAILED
S14Clean up workspace, worktrees and state fileharvest-clone.cjs, stdlib-candidates.cjsreferences/s14-cleanup.md(none — D5)(none)
S15Repoint the source repo onto the published package, per candidate — optional; Step 0 emits the planadopt-plan.cjs, install-package.cjs, retire-consumed.cjs (both t1k-cocos-playable-modularize-refactor), reuse-coverage.cjsreferences/s15-repoint.md(none — see reference)(none — see reference)
F0Project each framework candidate’s share of project linescandidate-projection.cjsreferences/f00-candidate-projection.mdF0F0-NO-PROJECT-ROOT F0-COVERAGE-FAILED

The F* rows are the framework lane, which runs alongside the repo-first S0–S14 lane above rather than replacing it: S0–S14 harvests one repo’s reusable code bottom-up, while F0–F4 packages a repeated subsystem top-down. The plan retired the old C0–C3 capability lane on 2026-09-16 after measuring its dedupe ceiling at only 2–5%, and replaced it with F0–F4.

Code meanings live in assets/failure-codes.json, keyed by code. S14 is deliberately not a ledger stage (D5): it runs after the S11 PR merges, so a row asserting it would have to predate its own evidence. harvest-ledger stage --stage S14 is rejected with exit 2. S15 is also not a ledger stage, and for a stronger reason than S14: its evidence is a PR on a repo this run’s schema has no slot for at all (references/s15-repoint.md).

Why this skill stays disable-model-invocation: true (deferred decision 7): S7 (package worktree), S10 (package PRs), S11 (record PR), S12 (Discord post), S13 (sync-back PR) and S15 (repoint PRs) write to shared repos or channels, and S0/S9 ask the user. The read-only front door a model may start on its own is t1k-cocos-playable-stdlib-scan (detector dry-run, status, report, and a scan into the per-user local queue; it writes to no repo).

Every PR this skill opens on The1Studio/cocos-stdlib (contribute/* and harvest/* branches):

  1. Carries a Consumer: line in its body: <org>/<repo>, <org>/<repo>#<pr>, <org>/<repo>:<path>, or none-yet (<reason of 20+ chars>). The last form is allowed on a ready PR like the others: the S8 gatekeeper APPROVE, not the consumer, is the merge gate, and the reason is the audit trail. When the reason says the package should wait for a consumer, ask the user whether to hold it (AskUserQuestion) rather than holding on your own judgment.
  2. Opens ready, with no no-automerge label, so auto-merge.yml on cocos-stdlib squash-merges it on a green ci (same default as t1k-cocos-base-stdlib-contribute Step 9; 2026-10-28 #536/#537, and #608/#548 sat draft forever because nothing promoted them). That workflow also refuses a contribute/* or harvest/* head with no gatekeeper APPROVE for its exact head sha, so the S8 verdict must be on record before ci completes: commit status gatekeeper = success, or an owner/member comment gatekeeper: APPROVE <sha> (REVISE and REJECT block). Post it right after the PR opens with .claude/modules/base/skills/t1k-cocos-base-stdlib-contribute/scripts/post-gatekeeper-status.cjs --pr <n> --head-sha <PR head> --verdict <validated verdict.json> (it refuses a verdict reviewed on another sha and never posts a hand-worded comment); auto-merge.yml only runs when ci completes, so a verdict posted later needs a ci re-run. Open draft with no-automerge ONLY on an explicit user or command instruction to hold. Never arm --auto.
  3. Is recorded in the ledger even if a later stage fails: record-run stamps S11 ok itself. S12 S12-NO-WEBHOOK stays non-blocking and unchanged.

Each is a direct AskUserQuestion in the main session — never a prose list, and never a paragraph the user might not answer (theonekit-core/.claude/modules/t1k-base/rules/always-ask-on-unresolved.md).

StageQuestionGuard
S0Confirm the inventory before probing the orgPreview-first: smoke a small --limit N first, surface it, then ask — theonekit-core/.claude/modules/t1k-base/rules/preview-first-batch.md. Required only when the worklist exceeds ~10 repos
S9Per ≤4 candidates: approve, reject, or defer this extraction?The approval table shows verdict, equivalence, gatekeeper verdict with its round count, and any near-dup (nothing reaches S10 unapproved)
S10None — the merge waits on ci, not on a personRuleset 22741411 requires 0 approving reviews and carries no required_status_checks rule, so there is nothing for a human to gate. The orchestrator watches ci to green and merges (s10-contribute.md)
S12What is the Discord thread ID?Only when harvest/config.json’s discord.threadId is null; write it back to the config on the S11 branch
S14None — the S11 PR merges under the same ci-green ruleIf it is still open, watch ci and merge. Cleanup is never a reason to merge

A non-interactive session stops at the first gate — it never auto-approves. An approval nobody gave is precisely what S9 exists to prevent.

Depth 0 spawns to depth 1; the fan-out cap and the depth budget are theonekit-core/.claude/modules/t1k-base/rules/agent-security-boilerplate.md § agent-only (8/3/2 by depth). This skill is a leaf consumer of that budget, not a setter of it — it neither sets its children’s depth nor reads its own.

WorkAgent
S0–S6a, S6b, S11–S15 Step 0 mechanicsno agent — deterministic CLI plus main-session writes (D17)
S3 knowledge sweept1k-corpus-scout (one read-only hop; its output is evidence/knowledge-sweep.json)
S3 architecture auditt1k-cocos-base-reviewer, read-only (writes evidence/architecture.json)
S7 extract, S10 resumet1k-cocos-playable-stdlib-contributor — one at a time (D18: the worktrees share one clone and node_modules, so two live agents clobber each other silently)
S8 gatekeepert1k-cocos-base-stdlib-gatekeeper (fable), one candidate at a time
S10 PR watchingt1k-ci-watcher — watches to terminal, never retries, fixes or merges
S11/S12/S13 gitt1k-git-manager
S13 lessonsONE background /t1k:sync-back, only when lessons is non-empty (U2)
S15 (optional, per candidate)main session or the S7/S10 contributor’s own continuation, plus t1k-git-manager + t1k-ci-watcher on the source repo’s PR — see references/s15-repoint.md

Routing rows live in theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md; this table is the harvest-specific map, not a second copy of that one.

A merged record (harvest/ledger.json, harvest/clone-index/<owner>__<name>.jsonl, harvest/reports/<owner>__<name>.md), any package PRs, at most one sync-back PR to theonekit-cocos (zero when lessons: [], U2), a Discord message, and — after S14 — no workspace, no state file and no worktree. When S15 ran for one or more candidates, also a repoint PR per candidate on that candidate’s own source repo — the run this pipeline extracted the code FROM, not cocos-stdlib or theonekit-cocos.

  • references/contracts.md — the interface freeze: script CLIs, JSON shapes, exit codes, the run-draft file, the evidence layout, the brief tokens, and the hook interaction note.
  • references/incident-history.md — tier-1 lessons earlier runs wrote down (D11). Read it before re-deriving a fix for something already recorded; S13 appends to it.
  • references/gatekeeper-rubric.md — the eleven rubric ids S8 grades against (GK-VALUE first).
  • references/s15-repoint.md — the optional stage that repoints a candidate’s source repo onto the package this pipeline just published, closing the loop S0–S14 leaves open on their own. Step 0 (adopt-plan.cjs) turns the provenance record S6b already writes into that plan.
  • t1k-cocos-base-stdlib-contribute — packages what this pipeline finds (Steps 0-2 decide).
  • scripts/resolve-canonical-cli.cjs — which installed copy of stdlib-candidates.cjs to run: the newest VALID copy, the others reported (never deleted; t1k modules update repairs them). Verdict tokens come from scripts/lib/verdict-vocab.cjs, mapped to the core vocabulary on read (SKIP is KEEP); without core’s normalize() the output says vocabulary: unverified on stderr.